Skip to main content

Windsurf MCP Setup

Connect your MCP bundles to Windsurf to give your AI coding assistant access to external tools.

Requirements​

  • Windsurf editor (latest version)
  • A bundle enabled in your MCPBundles dashboard
  • Credentials connected for providers in your bundle

Time to complete: 2-3 minutes

If you have terminal access (you're using Windsurf, so you do), the fastest way to connect is via the MCPBundles CLI:

pip install mcpbundles
mcpbundles init

This automatically discovers your bundles, writes the Windsurf MCP config, and handles authentication. No manual JSON editing needed.

After running mcpbundles init, restart Windsurf and your tools will be available.

Want more control? Use mcpbundles tools to browse available tools, or mcpbundles call <tool-name> to test a tool directly from your terminal.

Option B: Manual Setup​

Step-by-Step Setup​

1. Get Your Bundle URL​

  1. Log in to MCPBundles Dashboard
  2. Click on the bundle you want to use
  3. Scroll to the "Quick Setup" section (only visible when bundle is operational)
  4. Copy the MCP Server URL

2. Create Config File​

Windsurf uses mcp_config.json for MCP server configuration.

File location:

  • macOS/Linux: ~/.windsurf/mcp_config.json
  • Windows: %USERPROFILE%\.windsurf\mcp_config.json

If the file doesn't exist, create it.

3. Add Bundle Configuration​

Edit mcp_config.json:

{
  "mcpServers": {
    "your-bundle-name": {
      "serverUrl": "https://mcp.mcpbundles.com/bundle/YOUR-BUNDLE-ID"
    }
  }
}

Replace:

  • your-bundle-name - Short identifier (e.g., marketing)
  • https://mcp.mcpbundles.com/bundle/YOUR-BUNDLE-ID - Your actual bundle URL

Example:

{
  "mcpServers": {
    "marketing": {
      "serverUrl": "https://mcp.mcpbundles.com/bundle/abc123"
    },
    "dev-tools": {
      "serverUrl": "https://mcp.mcpbundles.com/bundle/def456"
    }
  }
}

4. Restart Windsurf​

  1. Quit Windsurf completely
  2. Reopen it
  3. Wait 10-20 seconds for MCP to initialize

5. Verify Connection​

Ask the AI assistant: "What tools do you have access to?"

Expected response: List of tools from your bundle(s).

Using Tools in Windsurf​

Once connected, Windsurf can use your tools for coding tasks.

Example Prompts​

Fetch data for development:

"Get the latest campaigns from Smartlead and create a TypeScript interface"

GitHub operations:

"List my GitHub repos and show which ones have open PRs"

Integration code:

"Fetch the latest HubSpot contacts and generate an import script"

Troubleshooting​

"MCP server connection failed"​

Fix:

  • Check URL is exactly as shown in dashboard
  • Verify bundle is enabled
  • Make sure serverUrl field is spelled correctly (camelCase)
  • Restart Windsurf

Tools don't appear​

Fix:

  1. Quit Windsurf completely
  2. Wait 5 seconds
  3. Reopen
  4. Wait 20 seconds for initialization

"Authentication required"​

Fix:

  1. Go to Dashboard → Providers
  2. Connect credentials for needed providers
  3. Try the tool again

See Provider Credentials Guide.

JSON syntax error​

Common mistakes:

Missing comma:

{
  "mcpServers": {
    "bundle1": { "serverUrl": "..." }  // ❌ Missing comma
    "bundle2": { "serverUrl": "..." }
  }
}

Should be:

{
  "mcpServers": {
    "bundle1": { "serverUrl": "..." },  // ✅ Has comma
    "bundle2": { "serverUrl": "..." }
  }
}

Fix: Use a JSON validator to check syntax.

Configuration Examples​

Multiple Bundles​

{
  "mcpServers": {
    "marketing": {
      "serverUrl": "https://mcp.mcpbundles.com/bundle/abc123"
    },
    "dev": {
      "serverUrl": "https://mcp.mcpbundles.com/bundle/def456"
    },
    "crm": {
      "serverUrl": "https://mcp.mcpbundles.com/bundle/ghi789"
    }
  }
}

Next Steps​

Need Help?​