Every time I've watched someone add a remote MCP server to Claude, ChatGPT or Cursor and get "couldn't connect", the problem was the same: one broken link in the OAuth discovery chain. The client gives you nothing useful. No log, no status code, just a failed connector.
So I wrote mcp-auth-check. You give it your MCP URL, it walks the auth chain the same way a real client does, and it tells you which link is broken. It's a small TypeScript CLI with zero runtime dependencies, read-only by default, and 26 tests.
npx github:manoj07ar/mcp-auth-check https://your-server.example.com/mcp
Here's what it checks, why each failure kills a connector, and how to fix the common ones.
The output first
This is a real run against a deliberately broken mock server from the CLI's test suite:
mcp-auth-check 0.1.0 -> http://127.0.0.1:8799/mcp
1. Unauthenticated request
PASS Unauthenticated POST returns 401 HTTP 401
PASS WWW-Authenticate header present Bearer challenge
WARN WWW-Authenticate has resource_metadata missing; clients can still find metadata at the well-known fallback http://127.0.0.1:8799/.well-known/oauth-protected-resource/mcp, but send resource_metadata for best compatibility
2. Protected Resource Metadata (RFC 9728)
PASS Protected Resource Metadata reachable 200 http://127.0.0.1:8799/.well-known/oauth-protected-resource/mcp
PASS PRM is a valid JSON object valid JSON
PASS PRM lists authorization_servers http://127.0.0.1:8799
FAIL PRM resource matches the MCP URL https://other.example.com/mcp does not match http://127.0.0.1:8799/mcp
3. Authorization Server Metadata (RFC 8414)
PASS Authorization Server Metadata reachable http://127.0.0.1:8799/.well-known/oauth-authorization-server
PASS issuer matches the authorization server URL http://127.0.0.1:8799
PASS authorization_endpoint present http://127.0.0.1:8799/authorize
PASS token_endpoint present http://127.0.0.1:8799/token
FAIL PKCE S256 advertised code_challenge_methods_supported is missing; MCP clients MUST refuse to proceed without it
WARN Client registration available (DCR / CIMD) no registration_endpoint and no CIMD support: users must paste a pre-registered client_id into every MCP client
4. Dynamic Client Registration (RFC 7591)
SKIP Dynamic Client Registration works not run (pass --dcr to register a throwaway client)
5. CORS
WARN CORS preflight on MCP endpoint HTTP 405; Access-Control-Allow-Origin is missing; ...
9 passed, 3 warnings, 2 failed, 1 skipped
Result: FAILED
Look at how much of that is green. The server returns a 401, serves its metadata, has an authorize and a token endpoint. It looks fine. It still won't work with any spec-following client, because of two lines.
It exits 1 when anything fails, so it works in CI too. Add --strict to fail on warnings as well, or --json if you want to parse the report.
What each check means
1. The unauthenticated request
The CLI sends a normal MCP initialize POST with no token. A remote MCP server must answer 401 with a WWW-Authenticate: Bearer ... header, ideally carrying resource_metadata="<url>".
Why it breaks connectors: this 401 is how the client finds out sign-in exists at all. Return a 403, a 200 with an error body, or a 401 without the header, and the client never opens a sign-in page. If the endpoint returns 2xx, the CLI flags it as open to anyone, which is a worse problem. On a non-localhost http:// URL you also get a FAIL, because the spec requires HTTPS.
A missing resource_metadata is only a warning if the well-known fallback works. Clients are supposed to try /.well-known/oauth-protected-resource/<path>, but I wouldn't rely on every client doing it.
2. Protected Resource Metadata (RFC 9728)
The CLI fetches the PRM document and checks that it's JSON, that it lists authorization_servers, and that resource matches the MCP URL.
Why it breaks connectors: resource is what the client sends as the RFC 8707 resource parameter, and it's what your tokens should be bound to. In the run above, the PRM says https://other.example.com/mcp while the server lives at /mcp on a different host. That's the classic copy-paste from staging, or a hard-coded URL behind a proxy. Clients that check it will refuse to continue. If resource is only a parent, like the bare origin, you get a warning, because some clients want an exact match.
3. Authorization Server Metadata (RFC 8414)
For the first authorization server, the CLI tries discovery URLs in the order the MCP spec gives clients: /.well-known/oauth-authorization-server, then the OpenID Connect variants. Then it checks:
-
issuermatches the authorization server URL (clients must reject a mismatch) -
authorization_endpointandtoken_endpointexist and are HTTPS -
code_challenge_methods_supportedincludesS256 - there's a
registration_endpoint(DCR) or Client ID Metadata Document support
Why it breaks connectors: the PKCE one is the sneaky one. Your server might fully support PKCE, but if the metadata doesn't say S256, MCP clients are required to stop. Missing registration is "only" a warning, but in practice it means every user has to create an OAuth client by hand and paste the ID into Claude or Cursor. Most won't.
4. Dynamic Client Registration (--dcr)
This is off by default because it creates a real (harmless) client record on your server. With --dcr, the CLI registers a public client and expects 201 with a client_id. A 200 gets a warning, since RFC 7591 says 201 Created.
Why it breaks connectors: Claude and ChatGPT register themselves on the fly. If /register rejects public clients (token_endpoint_auth_method: none) or loopback redirect URIs, sign-in dies right after the user clicks "connect".
5. CORS
The CLI sends an OPTIONS preflight from http://localhost:6274 (MCP Inspector's default origin; change it with --origin) and checks whether Authorization is allowed and whether WWW-Authenticate and Mcp-Session-Id are exposed.
Why it's only a warning: Claude and ChatGPT talk to your server server-to-server and don't care about CORS. Browser-based clients like MCP Inspector do. If you don't expose WWW-Authenticate, the browser hides the 401 challenge from the client's JavaScript and discovery fails without telling you why.
Fixing the usual suspects
No challenge header:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://your-server.example.com/.well-known/oauth-protected-resource/mcp"
Resource mismatch: build resource from one PUBLIC_URL config value plus the exact MCP path, and use that same value when you check the token audience. Don't derive it from the incoming Host header behind a proxy.
No PKCE S256: add "code_challenge_methods_supported": ["S256"] to your AS metadata. Then make sure the token endpoint actually enforces it. The metadata is a promise.
No registration: add a /register endpoint that accepts public clients and validates redirect URIs (HTTPS, or loopback for desktop clients).
CORS: answer OPTIONS on /mcp and set Access-Control-Allow-Headers: Authorization, Content-Type, Mcp-Protocol-Version and Access-Control-Expose-Headers: WWW-Authenticate, Mcp-Session-Id.
Fix, rerun, repeat until it's green. A server that gets everything right looks like this. Here's the end of a real --dcr run against my own template running locally:
4. Dynamic Client Registration (RFC 7591)
PASS Dynamic Client Registration works 201, client_id mcp_5H7euwN9-vfNnnuA9iR4zw
5. CORS
PASS CORS preflight on MCP endpoint origin http://localhost:6274 allowed with Authorization
PASS CORS exposes WWW-Authenticate and Mcp-Session-Id exposed
16 passed, 0 warnings, 0 failed, 0 skipped
Result: OK
What it doesn't do
It doesn't sign in, send credentials, or test your consent page, token exchange or refresh rotation. It checks discovery and metadata, which is where most "couldn't connect" bugs live. For the full flow you still want an end-to-end smoke test that plays the client (I covered that in my last post on testing remote MCP servers).
Try it
npx github:manoj07ar/mcp-auth-check https://your-server.example.com/mcp --dcr
Code, issues and the GitHub Action: https://github.com/manoj07ar/mcp-auth-check
It's MIT and free. If it finds something weird on your server, or flags something it shouldn't, tell me in the comments. I'd like the checks to match what real clients do.
That 16/16 run is my Remote MCP Connector Kit: a TypeScript (Workers, Vercel, Node, Docker) and Python remote MCP server template with OAuth 2.1 + PKCE, dynamic client registration and scoped tools, plus the test suite and smoke script. If you'd rather start green than debug your way there, it's here.
Top comments (2)
One check I'd add as a WARN: whether the authorization server sets authorization_response_iss_parameter_supported, for the RFC 9207 issuer check. The spec says SHOULD, and it's what lets a client catch a mix-up attack when it talks to more than one authorization server. When we checked 61 official remote MCP servers from SaaS vendors on Nov 4, all 61 got the 401 and PKCE S256 right, and 40 didn't advertise the issuer parameter. Nothing breaks without it today, which is exactly why nobody notices it's missing.
nice build, the PKCE S256 catch is clever