Skip to main content

Configuring MCP Server with Windsurf IDE

Overview​

Windsurf IDE (by Codeium) provides support for Model Context Protocol (MCP) servers through its Cascade AI system. This guide shows you how to connect your Cequence AI Gateway MCP server to Windsurf.

Configuration Steps​

1. Open Windsurf Settings​

Method 1: Using Command Palette

  1. Press Cmd + Shift + P (macOS) or Ctrl + Shift + P (Windows/Linux)
  2. Type "Open Windsurf Settings"
  3. Select Advanced → Cascade

Method 2: Using Settings Button

  1. Click the Windsurf - Settings button (bottom right corner)
  2. Navigate to Advanced → Cascade

2. Add MCP Server​

  1. In the Cascade settings, look for the MCP Servers section
  2. Click Add Server → Add custom server +
  3. Enter your MCP server configuration

3. Configuration Format​

Add your MCP server using the following JSON format:

{
  "mcpServers": {
    "your-server-name": {
      "command": "npx",
      "args": [
        "-y",
        "@cequenceai/mcp-remote",
        "your-mcp-server-url"
      ],
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

4. Configuration Parameters​

Replace the following placeholders:

  • your-server-name: A descriptive name for your MCP server (e.g., "salesforce-api", "github-repo", "databricks-ml")
  • your-mcp-server-url: The URL provided by Cequence AI Gateway after creating your MCP server

5. Additional Windsurf-Specific Options​

Windsurf supports additional configuration options:

  • disabled: Set to false to enable the server (default: false)
  • alwaysAllow: Array of tool names that should be auto-approved (default: [])

Example with auto-approval for specific tools:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@cequenceai/mcp-remote", "your-mcp-url"],
      "disabled": false,
      "alwaysAllow": ["get_user", "list_repositories"]
    }
  }
}

6. Multiple MCP Servers​

To configure multiple MCP servers in Windsurf:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@cequenceai/mcp-remote", "https://your-github-mcp-url"],
      "disabled": false,
      "alwaysAllow": []
    },
    "salesforce": {
      "command": "npx",
      "args": ["-y", "@cequenceai/mcp-remote", "https://your-salesforce-mcp-url"],
      "disabled": false,
      "alwaysAllow": []
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@cequenceai/mcp-remote", "https://your-slack-mcp-url"],
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

7. Save Configuration​

  1. Click Save or Apply Changes
  2. The MCP server should connect automatically
  3. If needed, restart Windsurf IDE

Alternative: Direct serverUrl Method​

Windsurf also supports a simplified configuration using serverUrl:

{
  "mcpServers": {
    "your-server-name": {
      "serverUrl": "your-mcp-server-url"
    }
  }
}

Note: The command + args method is recommended as it provides more flexibility and is consistent with other MCP clients.

Configuration File Location​

Windsurf stores MCP configuration in its settings:

macOS:

~/Library/Application Support/Windsurf/User/settings.json

Windows:

%APPDATA%\Windsurf\User\settings.json

Linux:

~/.config/Windsurf/User/settings.json

Verification​

Once configured, verify your MCP server is working:

  1. Open the Windsurf Cascade AI panel
  2. Check for a connection indicator next to your MCP server name
  3. Try a command related to your configured service
  4. Look for available tools in the Cascade interface

Using MCP Servers with Cascade​

In Cascade Chat​

Interact with your MCP server through natural language:

"Show me my Salesforce opportunities"
"Create a GitHub issue for the login bug"
"Query Databricks cluster status"

Tool Approval​

Windsurf will prompt for approval when Cascade wants to use an MCP tool:

  • Auto-approve: Add tool names to alwaysAllow array
  • Manual approval: Review and approve each tool call
  • Safety: Recommended to review tools before auto-approving

Cascade Flows​

Create automated workflows that use MCP servers:

  1. Open Cascade Flows
  2. Add steps that call your MCP server tools
  3. Chain multiple API calls together
  4. Save and reuse workflows

Troubleshooting​

MCP Server Not Connecting​

Issue: Server shows as disconnected or unavailable

Solutions:

  • Verify the JSON configuration syntax is correct
  • Check the MCP server URL is accessible
  • Ensure disabled is set to false
  • Restart Windsurf IDE completely
  • Check Windsurf logs (Help → Toggle Developer Tools → Console)

Authentication Failures​

Issue: "Authentication required" or "OAuth not configured"

Solutions:

  • Ensure OAuth authentication is completed in Cequence AI Gateway
  • Re-authenticate if the token has expired
  • Check that the MCP server has proper credentials configured
  • Verify your user has access to the MCP server

NPX Command Issues​

Issue: "Cannot find npx" or "npx not installed"

Solutions:

  • Install Node.js: nodejs.org
  • Verify Node.js is installed: node --version
  • Check npx is available: npx --version
  • Restart Windsurf after installing Node.js
  • Ensure Node.js bin directory is in your PATH

Tools Not Appearing in Cascade​

Issue: MCP server connected but no tools available

Solutions:

  • Verify the MCP server has endpoints configured
  • Check OAuth authentication is complete
  • Review MCP server deployment status in AI Gateway
  • Ensure proper API permissions are granted
  • Check Windsurf console for error messages

Permission Denied Errors​

Issue: "Permission denied" when calling tools

Solutions:

  • Check API credentials in Cequence AI Gateway
  • Verify OAuth scopes include required permissions
  • Ensure your user account has necessary permissions
  • Re-authenticate the MCP server connection

Best Practices​

Server Configuration​

  1. Descriptive Names: Use clear names that indicate the service and purpose
  2. Organize Logically: Group related services together
  3. Disable Unused Servers: Set disabled: true for servers you're not currently using
  4. Security First: Only auto-allow tools you fully trust

Tool Approval Strategy​

For Development:

{
  "alwaysAllow": ["read_file", "list_items", "get_status"]
}

For Production:

{
  "alwaysAllow": []  // Manual approval for all tools
}

Performance Optimization​

  • Disable unused MCP servers to improve startup time
  • Use specific tool approvals instead of blanket auto-approval
  • Monitor connection status in Cascade
  • Keep Node.js and npm updated

Example Configurations​

Development Workflow​

{
  "mcpServers": {
    "github-main": {
      "command": "npx",
      "args": ["-y", "@cequenceai/mcp-remote", "https://mcp.aigateway.cequence.ai/v1/servers/gh-abc"],
      "disabled": false,
      "alwaysAllow": ["get_repository", "list_pull_requests"]
    },
    "jira-tickets": {
      "command": "npx",
      "args": ["-y", "@cequenceai/mcp-remote", "https://mcp.aigateway.cequence.ai/v1/servers/jira-xyz"],
      "disabled": false,
      "alwaysAllow": ["search_issues"]
    }
  }
}

Data Analytics Workflow​

{
  "mcpServers": {
    "databricks-prod": {
      "command": "npx",
      "args": ["-y", "@cequenceai/mcp-remote", "https://mcp.aigateway.cequence.ai/v1/servers/db-prod"],
      "disabled": false,
      "alwaysAllow": ["list_clusters", "get_cluster_status"]
    },
    "bigquery-analytics": {
      "command": "npx",
      "args": ["-y", "@cequenceai/mcp-remote", "https://mcp.aigateway.cequence.ai/v1/servers/bq-analytics"],
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Additional Resources​