Connect tools to Windsurf
Windsurf exposes MCP integrations to Cascade. Treat each enabled server as an additional route to your files or external accounts, not merely a collection of prompt shortcuts. Begin with a single connection and verify the permissions and tools it actually exposes. Configuration examples for other editors are useful references, but remote connection field names are not interchangeable.
Configuration location
Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
Open the MCP configuration through Windsurf’s settings when possible to confirm the active file. Paths can differ in managed or future releases; check the client documentation if this location is not present.
1. Read requirements and choose a connection
Check the upstream project for runtime versions, supported transports, and any service account requirements. A local command launches on the machine running the editor’s MCP integration. A remote endpoint sends tool calls to a separate service with its own availability and privacy policy.
2. Edit the mcpServers object
Back up the active file and merge a named server entry under mcpServers. For local processes use command, args, and optional env. Windsurf documents serverUrl for remote endpoints; do not substitute another client’s url key without checking the documentation.
3. Refresh and review the tools
Use the app’s MCP refresh or restart flow, then inspect the server status and tool list in Cascade. If the server requires authentication, follow the supported flow for that provider. Do not work around a permission error by granting a broad administrator token.
4. Limit the first session
Try one non-destructive operation in a test workspace. Inspect the result and keep a human confirmation step for writes. Disable a server you no longer need rather than leaving long-lived credentials available to every future session.
Configuration example
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest"
]
}
}
}This example launches a browser server via npx. Review the package and its current README before running it. Merge the named entry into your existing configuration, and do not commit secrets. Examples demonstrate the file format; they do not bypass a client’s trust or approval prompts.
Playwright MCP installation and toolsTroubleshooting
Check valid JSON and the active file first, then distinguish command startup errors from remote transport or authentication failures. Refresh controls and remote transport support may change; check the client documentation if the installed version behaves differently.
Client versions and menus change. When the installed version differs from this guide, prefer its current documentation.
