Reference
The 12 checks
The twelve steps in the order Claude takes them, what each one tests, and exactly when it passes, warns or fails. Use this page to look up a step from a report.
#The twelve steps
| # | Step | Group |
|---|---|---|
| 1 | Connector address | Network |
| 2 | Public DNS | Network |
| 3 | HTTPS certificate | Network |
| 4 | Reachability, redirects and firewall | Network |
| 5 | MCP handshake | MCP |
| 6 | Session and tool list | MCP |
| 7 | Tool definitions | MCP |
| 8 | Sign-in discovery | Sign-in |
| 9 | Authorization server metadata | Sign-in |
| 10 | Client registration | Sign-in |
| 11 | Sign-in page | Sign-in |
| 12 | Token endpoint | Sign-in |
#1. Connector address
Reads the URL you gave Claude and works out the exact address it will call: scheme, host, port and path.
pass Passes when
- HTTPS on the standard port 443, with no credential in the URL and no trailing slash.
warn Warns when
- A non-standard port such as 8443 (a known cause of silent "Couldn't connect" in Claude).
- A query parameter that looks like a credential: token, key, secret, auth or password. The MCP spec forbids tokens in the query string and URLs end up in logs.
- A path that ends with a slash. Claude sends the resource without it, and its connector form has been reported to strip it.
fail Fails when
- The text is not a valid URL.
- The URL is not HTTPS. Claude only connects to HTTPS servers.
The fix. Use the full https URL on port 443, for example https://mcp.example.com/mcp. Move any key into a request header or use OAuth.
#2. Public DNS
Looks your host up on public DNS, the way Claude's servers do, and follows any CNAME chain.
pass Passes when
- The host resolves to at least one public IPv4 address.
warn Warns when
- The host is a bare IP address (certificates are normally issued for names).
- A CNAME chain longer than two hops. One team saw Claude never reach a host with a four-hop chain.
fail Fails when
- The name does not resolve in public DNS.
- It only has IPv6 (AAAA) records. Claude connectors are IPv4 only.
- It resolves only to private addresses, or to a mix of public and private ones. Claude requires every address to be public and rejects the whole name.
- The URL is a private IP address or an IPv6 address.
The fix. Add a public A record (IPv4) and remove private records from public DNS. A name that only resolves on your VPN, office network or home router cannot be reached by Claude.
Private ranges blocked: 10/8, 172.16/12, 192.168/16, 127/8, 169.254/16, 100.64/10, and other reserved blocks.
#3. HTTPS certificate
Opens an HTTPS connection to the host and port and checks the certificate chain.
pass Passes when
- A certificate from a public authority that covers the host name and has 14 or more days left.
warn Warns when
- Valid, but it expires within 14 days. When it lapses every Claude connection fails.
fail Fails when
- No answer on the port within 8 seconds, or the connection is refused.
- The certificate is not trusted: expired, self-signed, for another host name, or missing its intermediate certificate.
The fix. Serve the full chain (leaf plus intermediate), use a certificate from a public CA such as Let's Encrypt for this exact host, and turn on automatic renewal.
#4. Reachability, redirects and firewall
Sends the first MCP request (a JSON-RPC POST) and watches what answers: redirects, firewalls, bot challenges and slow starts in front of your server.
pass Passes when
- An answer within 5 seconds, no redirect and no block.
warn Warns when
- The first answer takes 5 to 10 seconds. Close to Claude's limit, so cold starts make connections fail now and then.
fail Fails when
- A redirect (3xx). Claude drops the Authorization header on a redirect to another host, so sign-in fails. Common causes are apex to www, http to https and a missing or extra slash.
- 403 or 429. A Cloudflare bot challenge, a WAF rule, rate limiting, or your own host check (the TypeScript SDK's DNS-rebinding protection answers 403 "Invalid Host" for unknown host names).
- A 5xx. The server crashed or is still starting.
- No answer within 15 seconds, or a first answer slower than 10 seconds.
The fix. Register the final URL, exempt the MCP path and /.well-known/ from bot protection and rate limits, add your host to the allowed hosts, and keep an instance warm.
A 404 or 405 here counts as reachable. The failure is reported on the next step, because it means the path is wrong, not that the network is.
#5. MCP handshake
Sends the MCP initialize request, asking for protocol version 2025-11-25, and reads the answer.
pass Passes when
- A 2xx answer, as JSON or an event stream, with a result that includes protocolVersion and declares the tools capability.
- Or a 401, which is how Claude is told to start OAuth. The sign-in steps then check the rest.
warn Warns when
- The handshake works but the server does not declare capabilities.tools.
- A WWW-Authenticate header on a 2xx response. Claude ignores it: sign-in only starts on a 401.
fail Fails when
- 404 (nothing at this path) or 405 (the path does not accept POST, often an old SSE-only endpoint).
- A content type other than application/json or text/event-stream, for example an HTML page: the URL is a website, not the MCP endpoint.
- No valid JSON-RPC result for initialize, an error result, or a result without protocolVersion.
- A 401 when you supplied a token: the server rejected it.
The fix. Use the exact path your server mounts (often /mcp) and Streamable HTTP: JSON-RPC POSTs to one endpoint. If the answer is a stream, make sure no proxy buffers it (nginx: proxy_buffering off).
#6. Session and tool list
Sends notifications/initialized, then asks for tools/list using the session id and protocol version from the handshake.
pass Passes when
- tools/list returns an array of tools within 10 seconds.
warn Warns when
- The list is empty, so Claude has nothing to call (or the tools are hidden behind sign-in).
fail Fails when
- The server rejects notifications/initialized with a 4xx or 5xx.
- The server forgets the session straight after creating it (404 on the next request). This happens when requests land on different instances that keep sessions in memory.
- tools/list errors, or does not return a tools array.
- tools/list takes longer than 10 seconds.
The fix. Answer the notification with 202 and no body, accept the mcp-session-id and mcp-protocol-version headers, and run stateless or keep sessions in shared storage.
Needs a server that works without sign-in, or a token. Otherwise this step is skipped with that reason.
#7. Tool definitions
Reads each tool's name, description and input schema.
pass Passes when
- Every name is 1 to 64 letters, numbers, underscores or dashes; every tool has a description; every inputSchema is a JSON Schema with type "object"; no duplicate names.
warn Warns when
- Any of those rules is broken. Claude may hide or reject those tools. The evidence lists each problem.
The fix. Fix each item listed in the evidence. Descriptions matter: Claude reads them to decide when to call a tool.
This step never fails; it warns. It is skipped when the server has no tools.
#8. Sign-in discovery
If your server answered 401, finds your protected resource metadata, first at the URL in the WWW-Authenticate resource_metadata parameter, then at /.well-known/oauth-protected-resource with and without your path.
pass Passes when
- The metadata is found, its "resource" matches the connector URL exactly (lowercase host, no default port, no trailing slash, no fragment), and "authorization_servers" lists at least one server.
warn Warns when
- The 401 has no resource_metadata pointer and the document was only found by probing. That fallback breaks on platforms that cannot serve /.well-known at the root.
- More than one authorization server is listed. Claude only uses the first and never falls back.
fail Fails when
- No metadata found. Claude never learns where your sign-in server is.
- "resource" is missing or does not match the connector URL.
- "authorization_servers" is missing or empty.
The fix. Answer with 401 and WWW-Authenticate: Bearer resource_metadata="https://your-host/.well-known/oauth-protected-resource/mcp", and serve that URL as JSON.
Not needed (and skipped) when the server works without sign-in or you gave a token.
#9. Authorization server metadata
Reads the sign-in server's own metadata, trying /.well-known/oauth-authorization-server first, then the OpenID configuration locations.
pass Passes when
- Metadata found, S256 PKCE advertised, and either a registration_endpoint or support for Client ID Metadata Documents.
warn Warns when
- The metadata issuer does not match the authorization server in your resource metadata.
- code_challenge_methods_supported does not list S256. Claude always sends S256 PKCE.
- Microsoft Entra: the connector URL has to be registered as an Application ID URI or the token request fails with AADSTS9010010.
fail Fails when
- No metadata found at the issuer (a WAF in front of the identity provider is a common cause).
- No token_endpoint.
- No registration_endpoint and no Client ID Metadata Document support, so Claude cannot register.
- response_types_supported does not include "code".
The fix. Serve RFC 8414 or OpenID discovery metadata, and make "authorization_servers" equal to the issuer exactly. For hosted providers (Auth0, Okta, Entra, Keycloak, Supabase) use their exact issuer URL.
#10. Client registration
Registers Claude as a client of your sign-in server. MCPatch posts a public-client registration with Claude's callback address, the way Claude does.
pass Passes when
- Dynamic registration answers 200 or 201 with a client_id within 10 seconds and keeps Claude's callback in the redirect URIs.
- Or the server supports Client ID Metadata Documents, so no registration call is needed.
fail Fails when
- Registration fails (any other status, or no client_id).
- It succeeds but drops Claude's callback URL.
- It takes longer than 10 seconds.
The fix. Turn on dynamic client registration (RFC 7591) with application/json bodies and allow https://claude.ai/api/mcp/auth_callback as a redirect URI, or support client ID metadata documents.
#11. Sign-in page
Opens your authorization endpoint with the same parameters Claude sends: the registered client, Claude's callback, an S256 challenge and the resource parameter.
pass Passes when
- The page accepts the request (no error, no 4xx) within 10 seconds.
warn Warns when
- The page's Content-Security-Policy form-action may block the final redirect back to claude.ai after the user signs in.
fail Fails when
- The request is rejected, either with a 4xx or with an error in the redirect (a callback that is not an allowed redirect, an unaccepted scope, or an unaccepted resource parameter).
- The page takes longer than 10 seconds, or does not load.
The fix. Allow https://claude.ai/api/mcp/auth_callback as a redirect URI, accept the scopes in your WWW-Authenticate scope parameter, and accept the connector URL as the resource.
With Client ID Metadata Documents this step is not tested, because the request would carry Claude's own client id, which MCPatch cannot use.
#12. Token endpoint
Posts a form-encoded request with a deliberately invalid authorization code, to see how the endpoint behaves. MCPatch never completes a real sign-in.
pass Passes when
- The endpoint accepts a form-encoded body and refuses the fake code with a JSON OAuth error such as invalid_grant, within 5 seconds.
warn Warns when
- The answer has no standard OAuth error.
- It is correct but slower than 5 seconds.
fail Fails when
- 415: the endpoint rejects form-encoded bodies, so every sign-in fails at the last step.
- 404 or 405: the token endpoint does not accept POST.
- A 5xx on an invalid code.
- No answer, or an answer slower than 10 seconds.
The fix. Parse application/x-www-form-urlencoded on the token route (Express: app.use(express.urlencoded({ extended: false }))), return {"error":"invalid_grant"} with status 400 for bad codes, and answer within 10 seconds.
#How the verdict is decided
- fail if any step fails. The headline names the first one:
Claude would stop at: MCP handshake. - warn if no step fails but at least one warns:
Passes, with 2 things to fix. - pass otherwise.
The protocol versions, tool changes and hidden-instruction results are shown separately and do not change this verdict. See Extra checks.