The Yirlo MCP server: run your outbound from any AI agent

What the Yirlo MCP server is

MCP, short for Model Context Protocol, is a shared standard that lets AI agents use tools they don't ship with. Yirlo runs a server at https://yirlo.com/mcp that speaks Streamable HTTP in the 2025-06-18 revision of the spec.

After that setup is done, routine tasks run from inside your chat window. Ask how many interested leads arrived recently, pause a campaign, change a daily budget, or open a conversation and have a reply drafted for you.

Authentication uses the same API key as the API and both SDKs. Send it as the header Authorization: Bearer YOUR_KEY, or as X-API-Key if your client prefers that.

Create your API key

Create a key in the app, on the page labeled API keys. Each key is prefixed yk_live_. One key works for REST calls, the MCP connection and both the Python and JavaScript SDKs, so there is just one secret to look after.

Handle the key as you would a password. Where your client allows it, load it through an environment variable or an input prompt, so it never sits in a file committed to a shared repository. The Cursor and VS Code examples below both do this.

The 33 tools, grouped by job

The tools fall into seven groups. Your agent picks the right one from your plain-language request, so you rarely need to name a tool yourself.

• Account and billing: get_account, get_balance. Check who the key belongs to and how much prepaid credit is left.
• Projects: list_projects and get_project show what you have, including whether a newly added one is still being set up or is ready to use. After your first project is in place, create_project adds another from a website domain, with its campaigns paused until you start them. project_analytics returns the results, and get_project_budget and set_project_budget let you check and adjust the daily spend.
• Campaigns: create_campaign builds a new audience and start_campaign launches it. stop_campaign pauses it and archive_campaign retires it. Use list_campaigns and get_campaign to look around, set_campaign_budget to adjust spending, and campaign_analytics to measure results.
• For hot leads and the inbox: who is interested comes from list_hot_leads, list_inbox and read_conversation display what people wrote, reply sends an answer, set_lead_status moves a lead's stage along, and set_lead_note records a comment on the record.
• Suppression: suppress_emails, suppress_domains. Put addresses or whole company domains on the do-not-contact list.
• Webhooks: add_webhook registers an endpoint, test_webhook fires a sample event so you can check the fields, and list_webhooks shows what is registered. Replies and hot leads can go to Zapier, n8n, Make or an endpoint you host.
• Team: list_team, invite_teammate. See who works in the project and invite someone by email.

Connect from Claude Code, Cursor, Windsurf, Cline, Gemini CLI and VS Code

In a terminal, register the server with the Claude Code CLI's mcp add command. Choose the http transport, name the server yirlo, and point it at https://yirlo.com/mcp. Pass the credential in a --header flag, using a header named Authorization whose value is Bearer followed by your key. Typing /mcp inside a Claude Code session then lists yirlo as connected. We checked this setup with Claude Code running get_balance and list_projects.

In Cursor, open Settings and choose MCP, or edit ~/.cursor/mcp.json for all projects, or .cursor/mcp.json in a single project's root folder. Beneath mcpServers, add an entry named yirlo. Its headers carry Authorization set to Bearer plus your key, and its url points to https://yirlo.com/mcp. Cursor detects the Streamable HTTP transport on its own. If you would rather keep the key out of the file, write ${env:YIRLO_API_KEY} in its place.

In Windsurf, open Cascade, choose MCP servers, then view raw config to reach mcp_config.json. Inside mcpServers, add a yirlo entry. The address goes in a field named serverUrl, which is Windsurf's name for remote servers, with the value https://yirlo.com/mcp. Next to it, put the same Authorization header made of Bearer and your key. Restart Cascade once the file is saved. Teams and Enterprise accounts may first need an admin to permit remote servers.

In Cline, open MCP Servers and the Remote Servers tab, then fill in yirlo as the name, https://yirlo.com/mcp as the URL, and Streamable HTTP as the transport. Alternatively, edit cline_mcp_settings.json. Under mcpServers, add yirlo with type streamableHttp, the url, and the Authorization header carrying Bearer and your key. Keep that type value, since leaving it out makes Cline assume the older SSE style for remote servers.

For Gemini CLI, open ~/.gemini/settings.json, or .gemini/settings.json inside a project. Under mcpServers, define yirlo with an httpUrl of https://yirlo.com/mcp, plus an Authorization header made of Bearer and your key. The httpUrl field is the one that selects Streamable HTTP. Afterward, run /mcp in Gemini CLI to see the Yirlo tools listed.

VS Code with GitHub Copilot reads .vscode/mcp.json, or an mcp.json at user level. The top-level property there is servers, unlike the mcpServers name other editors use. Declare yirlo with type http, the url https://yirlo.com/mcp, and an Authorization header set to Bearer followed by ${input:yirlo-key}. Next, add an inputs array holding one promptString item with the id yirlo-key, a description such as Yirlo API key, and password set to true. VS Code then requests the key a single time and hides the characters you type. Switch Copilot Chat to Agent mode and the tools are ready to use.

Any other agent or framework with MCP support over Streamable HTTP can connect using https://yirlo.com/mcp together with an Authorization header of Bearer and your key. If an agent can only make ordinary HTTP requests, the public API (docs at yirlo.com/api-docs) or an SDK fits better.

Example requests

Once connected, you talk to the agent the way you would talk to a colleague. A few asks that work well:

• Try asking the agent, "How many hot leads arrived this week?" It calls list_hot_leads, and brings in project_analytics if you want the wider picture.
• "Pause the campaign for dentists." The agent finds it with list_campaigns and calls stop_campaign.
• "Bump daily spend to $30 across the project." For that, the agent runs set_project_budget, or switches to set_campaign_budget when you point at one campaign.
• Tell the agent: "Reply to my newest interested lead and suggest Tuesday." It pulls the thread using read_conversation, writes a draft and puts it in front of you. Nothing goes out until you approve it, and only then does the reply tool run.
• "Never email anyone at my rival's domain." The agent runs suppress_domains, which keeps everyone at that company off your sends.
• "Create a hook for new hot leads and fire a test event." The agent runs add_webhook followed by test_webhook, which hands Zapier, n8n or Make a sample payload to map fields from.

Safety: reply and invite_teammate send real email

Two of the tools touch real recipients. reply emails the lead directly, and invite_teammate sends a genuine invitation to whatever address you supply. Neither action can be taken back, so tell the agent to check with you first by displaying the recipient, subject and complete body, then waiting for your approval.

The simplest way to make this a habit is to add a standing line to your agent's rules or system prompt: "Before calling reply or invite_teammate, show me the exact message and recipient and wait for my approval." Most clients also let you require manual approval for individual tool calls, which is worth switching on for these two.

Other tools change spending or reach. start_campaign begins sending, the budget tools set how much credit is used each day, and the suppression tools decide who is never contacted. Ask the agent to restate the change before it runs, especially a budget number, and check get_balance when a request involves money.

Questions

Related