Connect AI agents (MCP) to Yirlo
By the Yirlo team · Product details checked against the app
Yirlo's MCP server hands an AI agent control of your outbound through conversation. It can look up your credit balance, open the inbox, pause a campaign or respond to a hot lead. Any MCP-capable agent using Streamable HTTP needs only one URL and one key. Below you get the config, a trial request, sample questions and advice on keeping the key safe.
What the Yirlo MCP server gives your agent
Behind the endpoint https://yirlo.com/mcp is the Streamable HTTP transport from the 2025-06-18 MCP specification. Thirty-three tools sit behind it, each one a thin layer over a single call in the published Yirlo API. An agent connected there sees the same account, projects, campaigns and inbox that the app shows you.
Begin the first project in a browser on yirlo.com by pasting your site's URL. Yirlo reads what you sell and returns a set of proposed campaigns. After that, the agent can start further projects itself with create_project (the API and SDKs offer the same call), and it runs the day-to-day sending from within the AI assistant you already work in.
Before you connect: get your key
Keys are made on the API keys page of the app, at yirlo.com/app/api-keys. Each one begins with yk_live_. SDKs, the MCP server and direct API calls all accept the same key, which leaves a single secret for you to protect.
Have at least one project in your account before you test anything beyond get_account. Once a project exists, the agent has campaigns, leads and an inbox to work with.
Setup with the exact config
Any agent or framework with remote MCP support needs only a new server entry: the endpoint address plus your key sent as a bearer token. For clients that read a JSON file with an mcpServers object, an entry like the one below does the job, with YOUR_KEY swapped for your complete yk_live_ key:
{
"mcpServers": {
"yirlo": {
"headers": {
"Authorization": "Bearer YOUR_KEY"
},
"url": "https://yirlo.com/mcp"
}
}
}Field names vary between clients. Some write the transport as streamable-http, while others call the address field serverUrl. Layout aside, only two values matter: the endpoint https://yirlo.com/mcp, plus a header named Authorization that carries Bearer YOUR_KEY.
Clients that cannot attach an Authorization header can pass the key through the X-API-Key header. Use just one of the two methods.
A first test request
Once the server is added, restart the client if it asks you to, then check that the 33 tools appear in its tool list. Type this to your agent: "What is my Yirlo balance?" The agent calls get_balance and answers with your prepaid credit. Reading the balance changes nothing, so it makes a safe first call.
To check the connection outside an agent, send an initialize request from a terminal:
curl -X POST https://yirlo.com/mcp \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'A JSON reply that names the server confirms that the URL and key are right.
If you get an authorization error, check that the key is complete, that it has no stray spaces and that the header reads Bearer followed by one space and the key.
What you can ask
Ask in plain language and let the agent pick the tool. Requests that work well:
- "Count the hot leads that arrived this week." (list_hot_leads)
- "Pause the campaign for dentists." (stop_campaign)
- Make the spending cap $30 a day. (set_campaign_budget or set_project_budget)
- "Answer my most recent interested lead and propose Tuesday." (read_conversation first, then reply)
- "Stop all emails to a rival's domain." (suppress_domains)
- "Which campaign gets the most replies this month?" (campaign_analytics)
- "Send a test event to my Zapier webhook." (test_webhook)
The 33 tools by job
The tools fall into a few groups, so you can tell your agent which area to work in.
- Account and billing: get_account, get_balance
- Project tools: create_project (starts a further project after your first one, with its campaigns paused), set_project_budget, project_analytics, list_projects, get_project_budget and get_project (shows creation status).
- Everything about campaigns: list_campaigns and get_campaign to look, create_campaign to build, start_campaign and stop_campaign to run, archive_campaign to retire, set_campaign_budget and campaign_analytics for spend and results.
- For replies, list_hot_leads returns the warm prospects, list_inbox and read_conversation expose the threads, and reply sends your answer. Attach a note with set_lead_note and update the lead's status with set_lead_status.
- Suppression: suppress_emails blocks single addresses, and suppress_domains blocks whole companies.
- Webhooks: list_webhooks, add_webhook, test_webhook
- Team: list_team, invite_teammate
Actions that change things
Reading tools are harmless. Several others act on your live outbound: start_campaign and stop_campaign change what sends, the budget tools change spend, and suppression tools change who can be contacted.
Calling reply fires off a genuine email to the lead. Have your agent show you the draft and wait for your approval before sending, particularly the first time. Many agent clients also allow a confirmation step on every tool call, a smart choice for reply, create_campaign and the budget tools.
A practical routine is to let the agent read freely each morning, summarize new replies and hot leads, and propose answers. You then approve the ones you want sent.
Keeping the key safe
Whoever holds this key can read your conversations, email your leads and alter spend limits, so guard it like a password. Keep it in an environment variable or your agent's secrets vault, and have the config refer to it rather than pasting the value into files other people can see.
Keep it out of git repositories, screenshots, chat messages and support tickets. Share the setup with a teammate by sending them to the API keys page to create their own key, and give the key only to agents you run or trust.
A single key covers the API, the MCP server and the SDKs, so if it leaks, all three are exposed. Should you think someone else has seen it, generate a replacement at yirlo.com/app/api-keys immediately, then change the config on each machine that held the old one.
Agents that only call HTTP
Where an agent or framework has no MCP support, the public Yirlo API and the SDKs accept the same key, and the docs are at yirlo.com/api-docs. To send events such as a new reply or a hot lead on to other tools, set up signed webhooks that target your own endpoint, Zapier, n8n or Make. After that, the records can be stored in HubSpot, Salesforce, Pipedrive or any other CRM.
Questions
Which agents can connect to the Yirlo MCP server?
Works with any agent or framework that supports MCP over Streamable HTTP. Point it to https://yirlo.com/mcp and authenticate with Authorization: Bearer YOUR_KEY.
Where do I get the API key?
The API keys section at yirlo.com/app/api-keys is where keys are issued. A key carries the yk_live_ prefix, and the API as well as both SDKs will accept it.
Can I send the key a different way?
Yes. The server accepts the key as an Authorization: Bearer header or as an X-API-Key header.
How many tools does the server have?
Thirty-three tools make up the MCP server, and every one maps to a single endpoint in the published Yirlo API. Between them they handle projects, campaigns, the inbox, hot leads, suppression lists, webhooks, the account and the team. Four of the tools deal with lead sources: import_leads and get_import load a CSV of contacts you already have, while leads_from_post and list_posts start from a LinkedIn or X post you wrote and build a campaign for everyone who commented or replied.
Where does my first project start, and can the agent add more?
A first project begins at yirlo.com, where you submit your site's address and add credit. After that, the agent can start further projects with create_project, build and launch campaigns, load your own lead list with import_leads, work through replies and change budgets.
Does the reply tool really send email?
Yes. Each answer your agent writes lands in the lead's inbox as a true email message. If you want to check them first, ask the agent to hold every draft until you give the go-ahead.
Can the agent change my budget?
Yes. Daily spend can be changed with set_project_budget for the whole project or set_campaign_budget for one campaign. Every email that goes out costs around five cents, taken from the credit balance you topped up beforehand.
How do I stop emails to a competitor or a specific person?
Ask the agent to add the domain or address to your do-not-contact list. It uses suppress_domains or suppress_emails.
My agent only makes HTTP calls. What should I use?
Call the public API directly or go through one of the SDKs, and a single key covers both. Reference material lives at yirlo.com/api-docs.
What should I do if my key leaks?
Go to https://yirlo.com/app/api-keys immediately and replace it, then update the key in every agent config that used the old one.