DEV Community

Manoj Kumar
Manoj Kumar

Posted on

I wrote a 1-command check for remote MCP server auth. Here's what it catches

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

  • issuer matches the authorization server URL (clients must reject a mismatch)
  • authorization_endpoint and token_endpoint exist and are HTTPS
  • code_challenge_methods_supported includes S256
  • 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"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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)

Collapse
 
x1y1co profile image
X1Y1 •

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.

Collapse
 
parasraju profile image
Paras •

nice build, the PKCE S256 catch is clever