Connect Windsurf to Yirlo

What you need before you start

Begin with a project. Your first one always starts on yirlo.com: enter your website address there, which is also where the first payment happens. Later projects can start on yirlo.com too, or an agent in Windsurf can call create_project with your domain. Yirlo studies what you sell, then suggests campaigns. Either way, you also need an API key.

Mint a key from yirlo.com/app/api-keys inside the dashboard. Keys are prefixed yk_live_. One secret works for the REST API, the MCP endpoint and the SDKs, which leaves just one thing to protect.

Point Windsurf at https://yirlo.com/mcp. This is a remote endpoint using Streamable HTTP with MCP protocol version 2025-06-18, the transport Windsurf supports for hosted servers.

Add Yirlo to Windsurf

Open Cascade in Windsurf, click the MCP servers icon, then pick the raw config option to open mcp_config.json. Add a yirlo entry so the file reads:

{
  "mcpServers": {
    "yirlo": {
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      },
      "serverUrl": "https://yirlo.com/mcp"
    }
  }
}

Put your yk_live_ key where YOUR_KEY appears.

Windsurf uses the field name serverUrl for remote servers. If you already have other servers in the file, add yirlo next to them inside the same mcpServers object rather than creating a second one.

Save the file, then restart Cascade. When it comes back up, the MCP servers panel lists yirlo and the tools it provides.

As an alternative to the Authorization header, the server will read the key from an X-API-Key header. In Windsurf, stick with the Bearer form shown earlier.

Workspaces on a Teams or Enterprise tier can have a policy that blocks remote MCP servers by default. If Yirlo is still missing from the list after you restart the editor, ask an administrator to review that policy.

Run a first test request

Begin with requests that only read data. Open a Cascade chat and write: "Using yirlo, tell me about my account and what my balance is right now." Cascade should run get_account and get_balance, then reply with your account details and the prepaid credit you have left.

Follow up with: "Show me every Yirlo project and campaign I have." That triggers list_projects and list_campaigns. When the campaign names line up with the ones in the app, your setup is working from start to finish.

Ask something that needs a number, such as "What's the count of new hot leads over the past seven days?" Cascade will call list_hot_leads or the analytics tools and report back. Behind each tool is one public Yirlo API request, so the figures match what the app and the API show.

An authorization error from Cascade usually points at the config. Open mcp_config.json and confirm the header value is the word Bearer, one space, then the complete yk_live_ key. Stray quotes or line breaks inside the value will break it.

What you can ask Cascade to do

Thirty-three tools are available. Coverage includes projects (creating one too), campaigns, lead imports (import_leads and get_import), leads from your own LinkedIn or X posts (leads_from_post and list_posts), billing and account details, suppression lists, webhooks, the inbox and team members. You can phrase requests in everyday language and Cascade chooses the right tool.

Some asks that fit how developers and founders actually work:

• "How many hot leads this week?" reads your hot leads and gives you a count with the names and companies.
• "Pause the campaign for dentists." finds the campaign and stops it.
• "Make the daily budget $30." This updates the budget on the campaign or project. With emails billed at around five cents each, you can tell right away what daily volume that buys.
• "Show me the conversation with the last interested lead." reads the thread from the inbox.
• "Tell the latest interested lead that Tuesday works for me." Cascade writes the reply and delivers it to that lead by email.
• Prompt: "Put my rival's domain on the do-not-email list." The agent then places that domain on your suppression list.
• Prompt: "Register a webhook that triggers whenever a hot lead comes in, then push a trial event through it." This creates the endpoint that passes leads to your CRM via Zapier, n8n or Make, and runs a test through it.
• "Invite a teammate at this address." sends the team invite.
• "Compare campaign analytics for the last week and tell me which one is getting replies." reads campaign_analytics and ranks them.

Keep a hand on the actions that change things

Most tools only read. A few act in the real world: reply sends a real email to a real lead, start_campaign and stop_campaign change what goes out today, and the budget tools change how much credit you spend.

Build a habit of asking Cascade to show you the draft first. For example: "Read the last interested conversation and write a reply offering Tuesday. Show me the text before sending." Once you approve the wording, tell it to send.

For budgets, name the exact figure and the scope. "Set the daily budget for the dentist campaign to $30" leaves less room for misreading than "increase spend".

Windsurf asks for confirmation on tool calls depending on your settings. Leaving that on for the write tools is a sensible default.

Keeping the key safe

Guard the yk_live_ credential as you would a password. Anyone who holds it can see your leads and conversations and send emails in your name.

mcp_config.json sits on your machine, outside your repositories. Keep it that way. Do not paste the key into a project file, a README, a screenshot, a chat message or a shared snippet. If you share your config with a teammate, strip the key first and have them create their own at https://yirlo.com/app/api-keys.

Since the same secret also works for the REST API and the SDKs, keep it out of scripts that are committed to version control. Load it from an environment variable or a secrets manager instead.

If a key leaks or you are unsure who has seen it, create a new key in the app, put it in mcp_config.json, restart Cascade, and update anywhere else the old one was used.

Ask Cascade to read the config file only when you need to, and avoid pasting its contents into prompts. The key is sent as a header to https://yirlo.com/mcp and has no reason to appear in a conversation.

Troubleshooting

If yirlo is missing from the MCP servers list, confirm the JSON is valid (a stray comma is the usual cause), that the field is serverUrl and not url, and that you restarted Cascade after saving.

If the server is listed but calls fail with an authorization message, re-copy the key from the app and check the Bearer prefix.

If your Windsurf is on a Teams or Enterprise plan and the server is blocked, an admin has to allow remote servers first.

If a tool returns an empty list, check that you are asking about the right project. Ask Cascade to run list_projects and name the project you mean.

Questions

Related