Developer guide
Troubleshooting and FAQ
What "Couldn't reach the MCP server" usually means, which step to look at, and answers to the questions people ask most.
#"Couldn't reach" decoder
Run a check and look at the step in the headline. This table lists the usual cause for each one.
| Claude would stop at | Usual cause | First thing to try |
|---|---|---|
| Connector address | http instead of https, a non-standard port, a secret in the URL, a trailing slash. | Use https on 443 with a clean path. |
| Public DNS | The name only resolves privately, only has an IPv6 record, or has a private address mixed in. | Add a public A record, remove private ones. |
| HTTPS certificate | Expired, self-signed, missing the intermediate, or for another host. | Serve the full chain from a public CA. |
| Reachability, redirects and firewall | A redirect, a Cloudflare challenge, a WAF or rate-limit rule, a host check, a cold start. | Register the final URL; exempt /mcp and /.well-known from bot rules. |
| MCP handshake | Wrong path, an HTML page instead of MCP, an old SSE-only endpoint, a buffered stream. | Use the exact path and Streamable HTTP. |
| Session and tool list | Sessions lost between instances, notifications/initialized rejected, a slow tool list. | Run stateless, accept 202 for notifications. |
| Sign-in discovery | A bare 401, no protected resource metadata, a resource that does not match the URL. | Add the WWW-Authenticate header and the metadata. |
| Authorization server metadata | Wrong issuer, no S256, no registration endpoint, a WAF in front of the identity provider. | Use the provider's exact issuer URL. |
| Client registration | Registration disabled, or Claude's callback is not an allowed redirect. | Enable dynamic registration and allow the callback. |
| Sign-in page | Rejected redirect URI, scope or resource parameter. | Allow https://claude.ai/api/mcp/auth_callback. |
| Token endpoint | It only accepts JSON bodies (415) or is slow. | Parse form-encoded bodies. |
#Questions
MCPatch says everything passes, but Claude still fails
Then the problem is probably on Anthropic's side, or in something only a signed-in session shows, such as a token that works differently from what the check can try. Use Copy support report on the report page: it formats what passed, ready to paste into an issue on the connector repository, together with the ofid_ reference ID from Claude's error URL.
MCPatch is blocked, but Claude connects fine
MCPatch does not check from Anthropic's network, so a firewall that only admits Anthropic's range (160.79.104.0/21) blocks MCPatch and lets Claude through. The report says so at the reachability step. That is expected for a locked-down server; if you are sure it is a range rule, you can use the evidence in the report to confirm what answered.
Does it work for local (stdio) MCP servers?
No. MCPatch tests remote servers that Claude reaches over HTTPS. A local server that runs on your machine is not a connector.
Can I check localhost?
No, and neither can Claude. A localhost or private address fails at the DNS step. Put the server on a public address or use a tunnel, then check the public URL.
Is my token safe?
The token is sent over HTTPS to the checker, used for that single run and never stored or put in a report. Use a token meant for testing if you can, and rotate it if you shared it anywhere you should not have.
I hit the free limit
The free check allows 3 checks a day per visitor and 3 a day per connector. It resets 24 hours after the checks were made. For daily checks without limits, see the plans.
What does MCPatch send to my server?
A handful of ordinary MCP requests (initialize, notifications/initialized, tools/list), a few discovery requests for your sign-in metadata, and for OAuth servers a registration, an authorization request and a token request with a deliberately invalid code. It never completes a sign-in, never calls your tools and identifies itself as MCPatch in the User-Agent header.
Is a warning a problem?
A warning means the connector works today but has a risk: a certificate close to expiring, a slow first response, or a tool definition that Claude may hide. Fix them when you can; they tend to cause the "works, then suddenly does not" reports.
I found a wrong result
Email superwired.hq@gmail.com with the report link and what you expected. If a check was wrong we want to fix the rule.