Skip to main content

Windsurf Setup

Learn how to connect your deployed ToolBoost MCPs to Windsurf, the AI-powered coding assistant by Codeium.

Overview​

Windsurf is Codeium's AI coding assistant that supports MCP servers. By connecting ToolBoost MCPs, you can enhance Windsurf's capabilities with external tools and data sources.

Prerequisites​

  • Windsurf installed (Download here)
  • A ToolBoost account with at least one deployed MCP
  • Your project's API key from ToolBoost dashboard

Finding Your Connection URL​

  1. Visit your MCP's detail page on ToolBoost
  2. Confirm the MCP is deployed to your project
  3. In the "Use" section, find the Windsurf configuration
  4. Copy the connection URL:
https://toolboost.dev/server/author/mcp-name/mcp?api_key=YOUR_API_KEY

Configuration Methods​

Wind

surf offers two ways to add MCP servers:

Method 1: Windsurf Settings UI (Easiest)​

  1. Open Windsurf
  2. Go to Settings → Advanced → Cascade
  3. Find the MCP Servers section
  4. Click "Add MCP Server"
  5. Paste your connection URL
  6. Give it a descriptive name
  7. Click "Save"
  8. Restart Windsurf

Method 2: Manual Configuration File​

For more control and multiple servers, edit the configuration file directly.

Manual Configuration Steps​

1. Locate the Config File​

Windsurf stores MCP configuration in:

macOS:

~/.codeium/windsurf/mcp_config.json

Linux:

~/.codeium/windsurf/mcp_config.json

Windows:

%USERPROFILE%\.codeium\windsurf\mcp_config.json

2. Create/Edit the Configuration​

Create or open the mcp_config.json file:

{
  "mcpServers": {
    "your-mcp-name": {
      "serverUrl": "https://toolboost.dev/server/author/mcp-name/mcp?api_key=YOUR_API_KEY",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace:

  • your-mcp-name - A friendly identifier (lowercase, no spaces)
  • YOUR_API_KEY - Your ToolBoost project API key
  • author/mcp-name - The actual MCP path

3. Add Multiple MCPs​

For multiple MCP servers:

{
  "mcpServers": {
    "github": {
      "serverUrl": "https://toolboost.dev/server/github/github-mcp-server/mcp?api_key=YOUR_API_KEY",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    },
    "postgres": {
      "serverUrl": "https://toolboost.dev/server/modelcontextprotocol/servers-postgres/mcp?api_key=YOUR_API_KEY",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    },
    "filesystem": {
      "serverUrl": "https://toolboost.dev/server/modelcontextprotocol/servers-filesystem/mcp?api_key=YOUR_API_KEY",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

4. Save and Restart​

  1. Save the mcp_config.json file
  2. Completely quit Windsurf
  3. Restart Windsurf
  4. Open a project or file

Plugin Store Method​

Windsurf also has a Plugin Store for popular MCPs:

  1. Open Windsurf → Plugin Store
  2. Search for your MCP
  3. Click "Install"
  4. Enter your ToolBoost connection URL when prompted
  5. Activate the plugin
tip

The Plugin Store is great for discovery, but manual configuration gives you more control.

Verifying the Connection​

After restarting Windsurf:

  1. Open the Cascade panel (AI assistant)
  2. Check that your MCPs are listed in available tools
  3. Look for the MCP icon next to tool names

Test Commands​

Try these in Windsurf's Cascade:

For GitHub MCP:

List my GitHub repositories

For Filesystem MCP:

Show me the files in the current directory

For Postgres MCP:

What tables are in my database?

Windsurf should use your MCP tools to answer!

Common Issues & Solutions​

MCP Not Appearing​

Problem: MCP doesn't show up after restart.

Solutions:

  • Verify JSON syntax is correct (no trailing commas)
  • Check config file is in the right location
  • Completely quit Windsurf (don't just close window)
  • Check for error messages in Windsurf's output panel

Connection Errors​

Problem: "Cannot connect to MCP server" error.

Solutions:

  • Verify your internet connection
  • Check the connection URL is correct (copy fresh from ToolBoost)
  • Ensure your API key is valid
  • Confirm the MCP is still deployed in your ToolBoost project

Authorization Failures​

Problem: "Unauthorized" or 403 errors.

Solutions:

  • Verify API key in both serverUrl and headers.Authorization
  • Check for typos in the API key
  • Ensure API key hasn't been regenerated
  • Try copying the connection URL again from ToolBoost

Cascade Not Showing Tools​

Problem: Cascade panel doesn't show MCP tools.

Solutions:

  • Restart Windsurf completely
  • Check MCP connection status in Settings → Advanced → Cascade
  • Verify MCP is enabled (toggle may have been turned off)
  • Look for error messages in the Output panel (View → Output → Windsurf)

Complete Configuration Examples​

Basic Setup​

{
  "mcpServers": {
    "github": {
      "serverUrl": "https://toolboost.dev/server/github/github-mcp-server/mcp?api_key=tb_abc123",
      "headers": {
        "Authorization": "Bearer tb_abc123"
      }
    }
  }
}

Multiple MCPs​

{
  "mcpServers": {
    "github-work": {
      "serverUrl": "https://toolboost.dev/server/github/github-mcp-server/mcp?api_key=tb_work_key",
      "headers": {
        "Authorization": "Bearer tb_work_key"
      }
    },
    "postgres-analytics": {
      "serverUrl": "https://toolboost.dev/server/modelcontextprotocol/servers-postgres/mcp?api_key=tb_work_key",
      "headers": {
        "Authorization": "Bearer tb_work_key"
      }
    },
    "memory": {
      "serverUrl": "https://toolboost.dev/server/modelcontextprotocol/servers-memory/mcp?api_key=tb_work_key",
      "headers": {
        "Authorization": "Bearer tb_work_key"
      }
    }
  }
}

Different Projects​

You can maintain separate configurations for different workflows:

Development (mcp_config.json):

{
  "mcpServers": {
    "dev-postgres": {
      "serverUrl": "https://toolboost.dev/server/modelcontextprotocol/servers-postgres/mcp?api_key=tb_dev_key",
      "headers": {
        "Authorization": "Bearer tb_dev_key"
      }
    }
  }
}

Production (mcp_config.prod.json - rename when needed):

{
  "mcpServers": {
    "prod-postgres": {
      "serverUrl": "https://toolboost.dev/server/modelcontextprotocol/servers-postgres/mcp?api_key=tb_prod_key",
      "headers": {
        "Authorization": "Bearer tb_prod_key"
      }
    }
  }
}

Windsurf-Specific Features​

Cascade Integration​

Windsurf's Cascade AI deeply integrates with MCPs:

  • Smart suggestions: Cascade automatically suggests relevant MCP tools
  • Context aware: Understands which MCPs to use based on your code
  • Interactive: Can ask clarifying questions before calling MCP tools

MCP Tool Discovery​

Windsurf shows MCP tools in multiple places:

  • Cascade panel: Listed under "Available Tools"
  • Command palette: Search for MCP tools (Cmd/Ctrl + Shift + P)
  • Inline suggestions: MCP tools appear in code suggestions

Performance Optimization​

Windsurf caches MCP responses for better performance:

  • First call may be slow
  • Subsequent calls are faster
  • Cache invalidates when you restart or update config

Best Practices​

  1. Descriptive Names: Use clear MCP names (e.g., work-github, personal-postgres)
  2. Organized Config: Group related MCPs together with comments
  3. Regular Updates: Check ToolBoost for MCP updates
  4. Backup Config: Keep a backup of working configurations
  5. Security: Never commit API keys to version control

Advanced Tips​

Environment-Specific MCPs​

Use shell scripts to switch configurations:

#!/bin/bash
# switch-to-dev.sh
cp ~/.codeium/windsurf/mcp_config.dev.json ~/.codeium/windsurf/mcp_config.json
echo "Switched to development MCPs"

Keyboard Shortcuts​

Learn Windsurf shortcuts for faster MCP usage:

  • Cmd/Ctrl + Shift + C: Open Cascade
  • Cmd/Ctrl + K: Inline AI command
  • Cmd/Ctrl + Shift + P: Command palette

Debugging MCP Issues​

Enable verbose logging:

  1. Go to Help → Toggle Developer Tools
  2. Check the Console tab for MCP connection logs
  3. Look for error messages or warnings

Next Steps​

Need Help?​