Windsurf shows your MCP server as disconnected, or it never appears under "available MCP servers." Almost every case is one of these six. Work down the list.
1. Edit the right config file
Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Editing any other file does nothing. The Cascade panel's MCP section links straight to it — see MCP config file location for all clients.
2. Hit Refresh
Windsurf does not always reload automatically. Open the Cascade panel → MCP section → click Refresh. If that fails, restart Windsurf fully.
3. Validate the JSON
A trailing comma or missing brace makes Windsurf ignore the whole file silently. Validate it. The top-level key is mcpServers, and stdio servers need command + args.
4. Fix PATH (spawn npx ENOENT)
GUI apps on macOS do not inherit your shell PATH, so npx/node may not be found. Replace "command": "npx" with the absolute path (which npx to find it), or launch Windsurf from a terminal.
5. Test the server standalone
Run the exact command from your config in a terminal. If it crashes there, the issue is the server or its arguments, not Windsurf. Fix the token, path, or DSN first.
6. Read the logs
Windsurf surfaces MCP errors in its output/logs. The real reason — bad token, missing scope, crashed process — is usually printed verbatim. Match it to the server's docs.
Still stuck?
If the command works in a terminal but not in Windsurf, it is almost always PATH (#4). Setting up fresh? See the Windsurf MCP setup guide. On a different client? See Cursor MCP not working or Claude Desktop MCP not loading.