MCP connection errors: stdio, HTTP and configuration
MCP will not connect? Check launch commands, JSON, stdio, HTTP endpoints and authorization in order, with a practical troubleshooting table.
An MCP server does not appear in the client or loses its connection. Start at the first failing stage: is the configuration loaded, does the process start, does connection succeed and is the required tool available? This order prevents a path error from being obscured by unrelated credential changes. Record the exact error and change one setting at a time.
Identify the transport first
With stdio, the client launches a subprocess and exchanges protocol messages through its standard input and output. Streamable HTTP connects to an HTTP endpoint of an independent server process. The older HTTP+SSE mechanism is distinct. A response in a web browser does not establish a working MCP connection. Check the documented transports supported by both the server and your chosen client.
Look up the name, package or repository in the registry search. Read the declared connection and create a matching client configuration when a launch template is available. If several entries have similar names, use the comparison tool. Do not place a remote URL into a field intended for a local executable command.
Check local startup and JSON
A stdio process needs its runtime and an executable command available in its own environment. Desktop applications can inherit a different environment from your terminal. Check the command, argument array, working directory and required variables. Use the client’s actual configuration location. A valid JSON document in the wrong directory will not become active through repeated server restarts.
The batch checker can read supported JSON configuration structures and resolve registry references. It does not run those servers, so it cannot prove startup succeeds. Pay attention to the limits reported by the tool. TOML and other client configuration formats require their own format checks. Keep parsing, entry lookup and live execution separate when recording what you have verified.
| Observation | Possible cause | Next check |
|---|---|---|
| Server missing | Unread file or wrong structure | Client format and location |
| Command not found | Missing runtime or search path | Startup environment and executable path |
| Unreadable protocol | Unrelated output on stdout | Separate protocol output from logs |
| HTTP 401 or 403 | Rejected authorization or access | Server message and permissions |
| HTTP 404 or 405 | Path, method or session mismatch | Documented endpoint and request context |
| Tool missing | Different version or capability | Tool list against documentation |
Interpret HTTP responses in context
The MCP transport specification for revision 2025-11-25 allows Streamable HTTP to return 405 to GET under defined conditions. A browser request alone is therefore not a general health test. A 404 during an established session can also indicate an expired session identifier. Read the response in the context of the client and its documented protocol revision instead of immediately treating one status code as evidence that the service is down.
Finish with a small, observable test
Keep a local copy of the previous configuration without publishing its secrets in a ticket.
Check format and launch method first, then authorization and connection. Record which edit resolves each observed failure.
Display the tool list in the client. Choose one bounded operation appropriate for your test environment.
Compare the output with your expectation. Document client version, server version and remaining limits so another person can repeat the same check.
- Does every stderr message indicate failure?
- No. stdio servers may emit ordinary diagnostic messages there. Read the message together with the process status.
- May startup banners appear on stdout?
- For stdio, that stream is reserved for valid protocol output. Extra text can interfere with communication.
- Does HTTP 200 prove that the server works?
- No. Check initialization, the tool list and the operation you actually need through a suitable client.
- Why change one setting at a time?
- It preserves evidence of which change repaired the failing stage. Several simultaneous edits make the result harder to reproduce.
Sources checked on 1 October 2026. The checklists are editorial suggestions for your own environment.
- MCP specification 2025-11-25: transports
Show retrieval command
curl -s https://modelcontextprotocol.io/specification/2025-11-25/basic/transports