MCP server not connecting: the checks that fix most clients, then each client's own fixes

Test the server without a client

A remote MCP server answers a plain POST. If this fails, no client setting will fix it:

curl -si https://example.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

• 200 with a result naming the server: it's reachable, so the problem is in the client config.
• 401: the server wants a sign-in or a key. The WWW-Authenticate header says which, and a server with OAuth points to its metadata there.
• A redirect (301, 302, 307, 308): use the address it redirects to. Clients drop the Authorization header when a redirect goes to another host.
• 405 or 404: wrong path, or a client set to the legacy SSE transport talking to a Streamable HTTP server.

For a local server, run its command and args in a terminal instead. If it fails there, it fails in the client, and the terminal shows why.

The checks that fix most clients

1. The JSON file parses. In Cline one broken entry stops every server; elsewhere a trailing comma or a missing brace drops the file. Run it through a JSON validator.
2. The entry is under the key that client reads: mcpServers in most, context_servers in Zed, [mcp_servers.<name>] tables in Codex's config.toml, servers in VS Code's mcp.json.
3. The transport is right. Some clients read a url with no type as legacy SSE; set the type the client documents for Streamable HTTP.
4. OAuth isn't blocked by a header. Several clients skip their sign-in prompt whenever an Authorization header is present, so a stale key fails quietly instead of asking you to sign in.
5. Variables expanded. ${VAR} that a client doesn't expand reaches the server as literal text and comes back as a bad token. Some clients only expand an approved list, and all of them only see variables set before the app started.
6. The client reloaded. Claude Desktop needs a full quit; Kiro applies saved changes between turns; most editors need the server restarted from their MCP panel or a reload.
7. Local servers use absolute paths and log to stderr only. A client may start them with / as the working directory and a small set of environment variables, and anything printed to stdout corrupts the protocol.

Fixes by client

• Claude Code: claude mcp list, scopes, /mcp, MCP_TIMEOUT.
• Claude Desktop, local servers: claude_desktop_config.json, the full quit, mcp logs.
• claude.ai and Claude Desktop custom connectors: reachability from Anthropic's cloud, redirects, plans.
• Cursor: mcp.json locations, MCP Logs output, the tool toggle.
• Codex CLI: config.toml tables, trust, "Waiting for startup".
• Windsurf
• Gemini CLI
• VS Code with Copilot
• Cline: the shared settings file, type streamableHttp.
• Zed: context_servers, the status dot, profiles.
• Kiro: which mcp.json wins, approved env vars, the issuer check.
• Warp: where Warp finds servers, auto-spawn, View Logs.
• Goose: config.yaml, package runners, sessions, OAuth clients.
• Junie: mcp.json locations, the /mcp statuses, Authorize, millisecond timeouts.
• OpenCode
• Antigravity CLI

Taskhold

Taskhold's server is https://taskhold.com/api/mcp. Clients with OAuth add the URL with no header and sign in, with no sign-up first: the first time the agent uses Taskhold it gives you the link to start the 7-day trial. Its 401 names the cause (missing_key, bad_header, not_a_taskhold_key or unknown_key), and Taskhold troubleshooting covers the rest. Once connected, every agent's tasks, steps and questions show on the live board.