# Mav MCP > Mav connects your AI client directly to a full recruiting pipeline, letting you manage candidates and qualify leads via SMS conversation. Use automated playbooks to send human-like outreach, track replies, and schedule appointments without touching an inbox. ## Overview - **Category:** human-resources - **Price:** Free - **Tags:** ai-recruiting, candidate-screening, sms-engagement, automated-followup, lead-qualification, conversational-ai ## Description **Mav connects your AI client straight into a recruiting pipeline, letting you handle candidate screening and lead qualification using SMS conversations.** You don't have to touch an inbox; your agent manages it all for you. **To get started, you can use `create_lead`**. Running this tool both creates the new candidate record in the system and immediately kicks off an automated screening playbook designed just for them. When you need to check up on a specific person, **you've got `get_lead`**. It pulls every current detail for a single lead ID, giving you their qualification score and full status report. You can also use **`list_leads`**; this shows you every candidate in the entire system, along with basic metrics like what stage they're at right now. Want to see exactly what kind of automated workflows are available? Use **`list_playbooks`** to display all the screening playbooks Mav has built out. If you need to know how a specific playbook works, **you run `get_playbook`**. This pulls the full structure and ruleset for any given automation. For keeping track of everything that's happening—the replies received or when a campaign finishes—**you use `list_activities`**. It gives you a chronological list of every recent event across your entire account. You can also check what campaigns are running by using the playbook tools to manage outbound SMS outreach, letting you launch and monitor large-scale recruiting efforts targeting lists of candidates. Managing an active lead means controlling the automation. **You can use `update_lead`** to change specific data points on an existing record, like their salary expectations or when they're available for interviews. If a candidate needs manual eyes on them before the playbook continues, you run **`stop_playbook`**. This stops any ongoing automated screening process for that lead so you can step in. Sometimes a lead isn't ready for outreach. You can use **`opt_out_lead`** to manually remove a candidate from all future SMS communications and campaigns, keeping the pipeline clean. The system also gives you direct control over playbooks; besides stopping them, your agent handles the whole sequence of automated conversations. Here's how it works: Your AI client talks directly to these tools. By calling **`create_lead`**, you initiate an automatic screening conversation flow with a target prospect. If you need deep background data on one candidate, calling **`get_lead`** pulls all current details, including their history and status. You use the list functions—**`list_leads`**, **`list_playbooks`**, and **`list_activities`**—to audit your entire operation. To manage the content of those conversations, you can update lead data with **`update_lead`**. When a playbook needs to pause for human review, **you run `stop_playbook`**. You're never stuck in an inbox because every action—from creating the initial record via **`create_lead`** to opting someone out using **`opt_out_lead`**—is handled through these specific tools. ## Tools ### create_lead Creates a new candidate record and immediately starts an automated screening playbook for them. ### get_lead Retrieves all current details, including qualification score and status, for one specific lead ID. ### get_playbook Pulls the full structure and ruleset of a specific automated screening playbook. ### list_activities Retrieves a chronological list of all recent events, such as replies or campaign launches, across your account. ### list_leads Lists every candidate in the system and provides basic metrics like their current qualification status. ### list_playbooks Displays all screening playbooks you have created, allowing you to see what workflows are available. ### opt_out_lead Manually removes a lead from all future communications and campaigns. ### stop_playbook Stops an ongoing automated screening process for a specific lead, usually because the candidate needs to be manually reviewed first. ### update_lead Changes specific data points (like salary expectation or availability) on an existing lead record. ## Prompt Examples **Prompt:** ``` Show active SMS campaigns and completion rates. ``` **Response:** ``` Active Campaigns: 3. 'Retail Store Manager' (450 candidates, 68% reply, 45% completion ⭐). 'Warehouse Staff' (1,200 candidates, 42% reply, 28% completion). 'Customer Support' (300 candidates, 55% reply, 38% completion). Total screened today: 145. Qualified: 42. ``` **Prompt:** ``` Launch a screening campaign for the new Warehouse Staff list. ``` **Response:** ``` Campaign launched! ✅ Campaign ID: cmp_890. Target list: 'Warehouse_Applicants_Q2' (150 candidates). Screening flow: 'Basic Warehouse Qualification'. First SMS sent to 150 candidates. Estimated completion time: 2-4 hours. ``` **Prompt:** ``` Show screening results and transcripts for qualified candidates. ``` **Response:** ``` Qualified candidates: 3 (Retail Manager). 1) Sarah J. (Score: 95%, 'Has 5+ years retail management experience. Available immediately.'). 2) Mike T. (Score: 88%, '3 years experience, flexible schedule.'). Transcript for Sarah available: Link to transcript. Move to interview stage? ``` ## Capabilities ### Initiate automated screening conversations The server starts a new lead record and triggers an automated playbook conversation flow with a target prospect. ### Retrieve detailed lead records It pulls all current details for a specific candidate, including their status and history. ### Manage outbound SMS campaigns You can launch and track large-scale recruiting outreach campaigns targeting lists of candidates. ### Control playbook execution The agent stops or pauses a running qualification playbook on a lead, allowing manual intervention before restarting it later. ### Audit campaign activity and status It lists recent events across all campaigns—like replies received or playbooks that finished—giving you an audit trail. ## Use Cases ### The weekly status report dump A Talent Acquisition Manager needs to know which campaigns hit their goal this week. Instead of downloading 10 CSVs and manually counting replies, they run `list_activities` through the agent. The agent compiles a clean summary: 'Total screened today: 45; Qualified: 12.' Problem solved in seconds. ### The urgent manual fix A recruiter finds a promising lead, but the automated playbook is running an irrelevant sequence. They use `stop_playbook` to halt the conversation and then use `update_lead` to manually input new data points (like 'Budget: High') before resuming it. ### High-volume cold outreach launch The HR Ops team has a list of 500 candidates who fit a niche role. Instead of emailing them, they use `create_lead` with the entire batch and specify the 'Niche Tech Playbook.' The agent handles the initial SMS flow for all 500 leads automatically. ### Checking compliance status A candidate texts back requesting to be removed from marketing outreach. Instead of forwarding it to a compliance officer, the agent detects the request and calls `opt_out_lead` immediately, logging the action and protecting the company. ## Benefits - Stop relying on manual status updates. Use `list_leads` to instantly see every candidate's current qualification status, letting you filter out cold contacts immediately. - Don't write follow-up scripts from scratch. Calling `get_playbook` shows the exact ruleset used for screening, helping your agent execute multi-step conversations flawlessly. - Manage compliance and risk with one call: use `opt_out_lead` to instantly remove a candidate from all mailing lists when they request it—no dashboard clicks required. - Keep your outreach running even if you're offline. Use `create_lead` to start an automated campaign right away, triggering the playbook without constant supervision. - Get the full picture of what happened last week by calling `list_activities`, giving you a comprehensive audit trail of every interaction and metric. - Correctly pause workflows when needed. If a candidate needs a manual review, use `stop_playbook` to halt the automated sequence, ensuring no messages are sent prematurely. ## How It Works The bottom line is: your AI client acts as an intermediary, using Mav's tools to perform complex recruiting tasks without needing direct API access. 1. First, subscribe to the Mav server and input your unique API Key into your AI client. 2. Second, tell your agent exactly what to do (e.g., 'List all leads that haven't replied in 7 days') by calling a tool like `list_leads`. 3. Third, the agent runs the function, pulling structured data back that you can then use for follow-up actions or reporting. ## Frequently Asked Questions **How do I check if a candidate is already in the system using Mav MCP Server?** You use `list_leads` to pull a list of existing IDs, or if you have an ID, call `get_lead`. This confirms their current status and ensures you aren't duplicating records before running any playbooks. **Can I start a campaign for leads that are already in the system?** Yes. You don't need to use `create_lead`. Instead, first confirm their status with `get_lead`, and then you can proceed to run or restart the required playbook. **What is the difference between list_leads and list_activities?** `list_leads` gives you a snapshot of people (the leads) and their current state. `list_activities` gives you an event log—it shows *what happened* across all campaigns over time, like 'Lead X replied to message Y'. **How do I prevent my agent from spamming candidates?** You can use `opt_out_lead` immediately if a candidate asks to stop contact. This is the safest way to ensure they are permanently removed from all automated outreach. **If I use `update_lead`, what data formats does it require for different fields?** The required format depends entirely on the field you're updating. You must check the specific API documentation to confirm if a value needs to be a string, boolean, or integer before calling `update_lead`. **If an automated screening conversation gets stuck, how can I use `stop_playbook`?** You pass the lead ID and the playbook ID. This action immediately halts all communication for that specific candidate, letting you manually review the status or restart the flow. **When I first connect to Mav, what should I use `list_leads` for?** You run `list_leads` to pull a full snapshot of all existing candidates into your agent's context. This lets you verify the current scope and build an initial dataset before launching any campaigns. **Are there rate limits when I use the `create_lead` tool?** Yes, Mav enforces standard API usage limits. If your agent exceeds a threshold, it will receive an HTTP 429 error code. You'll need to build exponential backoff into your workflow. **Can I trigger AI screening conversations?** Yes. Launch SMS or web-based screening flows and track candidate responses automatically. **How does Mav authentication work?** Mav uses a custom API Key header against `hiremav.com/api/v2`. **Can I track campaign engagement metrics?** Yes. Monitor open rates, reply rates, completion rates, and candidate drop-off points.