How to Set Up MCP in Windsurf

Windsurf's Cascade agent supports MCP servers via HTTP transport. Once connected, Cascade can call MCP tools mid-conversation — querying documentation, fetching context, or running any capability you expose — without you leaving the editor.

This guide covers how to connect an MCP server in Windsurf, how to verify it's working, and how to use AgentReady's hosted MCP server to make any website queryable from Cascade.

How MCP works in Windsurf

Windsurf supports MCP via HTTP — meaning remote MCP servers accessible over HTTPS work out of the box. Local stdio servers require a wrapper to expose them as HTTP, but any hosted MCP server works directly with a URL.

When you add an MCP server, Cascade discovers its available tools at session start. During a conversation, Cascade can call those tools autonomously when it determines they're relevant to your query. You don't invoke tools manually — you just ask Cascade questions and it decides when to call them.

Where to configure MCP in Windsurf

MCP servers in Windsurf are configured in the Windsurf settings file. Open the Command Palette (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows), then search for Open Windsurf Settings (JSON).

MCP servers live under the mcpServers key. The format differs slightly by transport type.

Adding an HTTP MCP server

For remote servers (like AgentReady), use the url field:

{
  "mcpServers": {
    "agentready": {
      "url": "https://www.agentready.it.com/api/mcp"
    }
  }
}

Save the file and restart Windsurf. Cascade will pick up the new server on the next session start.

Adding a local stdio server

For local servers (npm packages that run as a subprocess), use command and args:

{
  "mcpServers": {
    "agentready": {
      "command": "npx",
      "args": ["-y", "@agentreadyweb/mcp"]
    }
  }
}

Both approaches work. The HTTP URL option is simpler — no npm install, no version management, and the server is always up to date.

Verifying the connection

After restarting Windsurf, open a new Cascade chat and ask:

What MCP tools do you have available?

Cascade should list the tools from your connected server. For AgentReady, you'll see:

• list_sites — see all indexed websites
• submit_site — index a new website
• ask_site — query any indexed site with a natural language question
• refresh_site — re-crawl a site after content updates

If tools don't appear, double-check the JSON syntax in your settings file and confirm Windsurf has been fully restarted.

Querying documentation from Cascade

Once AgentReady is connected, Cascade can answer questions about any indexed website. Try:

Using AgentReady, what are the rate limits for the Stripe API?

Ask AgentReady: how do I configure ISR in Next.js?

What does Supabase's realtime feature support according to their docs?

Cascade calls ask_site automatically and returns a cited answer grounded in the actual documentation — not its training data.

If the site you're asking about isn't indexed yet, Cascade can call submit_site to kick off indexing. It takes about 60 seconds, after which ask_site works on that domain too.

Multiple MCP servers

Windsurf supports multiple MCP servers simultaneously. Add them as separate keys under mcpServers:

{
  "mcpServers": {
    "agentready": {
      "url": "https://www.agentready.it.com/api/mcp"
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
    }
  }
}

Cascade merges all available tools from all connected servers and calls whichever is appropriate for each query.

Troubleshooting

Tools not appearing: Confirm the JSON in your settings file is valid (no trailing commas, correct bracket nesting). Restart Windsurf fully — not just the window.

HTTP server not connecting: Check that the URL is reachable in a browser. AgentReady's endpoint is at https://www.agentready.it.com/api/mcp and should return a 200 on GET.

Cascade not calling tools automatically: Explicitly tell Cascade to use a specific tool. "Use AgentReady to answer this" is more reliable than relying on Cascade to decide unprompted, especially early in a session.