MCP OAuth Debug

When the MCP OAuth login returns neither a token nor a URL.

How to start

1. Call a tool that requires an accountLook for HTTP/1.1 401 with WWW-Authenticate and resource_metadata=... If you get 200 the tool is public: pick another one (profile, library, credits, orders).curl -sS -i -m 20 -X POST "$MCP_URL" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"<tool_with_account>","arguments":{}}}' | head -30
2. See which authorization server the metadata points toLook for authorization_servers[] and scopes_supported[] in the protected-resource document.curl -sS -m 20 "$MCP_URL_ORIGIN/.well-known/oauth-protected-resource"
3. Confirm dynamic client registrationWith a registration_endpoint the whole flow is automatic — no manual client registration, however much the client's error message suggests otherwise.curl -sS -m 20 "$AUTH_SERVER/.well-known/oauth-authorization-server"
4. Confirm the token landed on diskOnly the .client.json (the registration result) means the OAuth did NOT finish. Registration alone is not authentication.ls -la "$TOKEN_DIR" # e.g. ~/.config/<client>/mcp-tokens/, ~/.mcp/tokens/

When you will use it

• The client says "connected" and never asks for a loginThe server connects, tools/list works, and every account tool returns 401 forever. The skill forces the challenge the client never saw.
• 401 on every callBefore blaming the provider: four commands, in order, separate infra, client and server and tell you which of the three is returning 401.
• Which authorization server?Reads the protected-resource metadata and shows where the server points (authorization_servers, scopes_supported) — no guessing.
• Do I have to register a client by hand?If the server announces a registration_endpoint you create the client_id on the spot (public client + PKCE S256) instead of waiting on a manual signup.
• The token expired and the refresh never comesThe redirect_uri, PKCE and resource indicators checklist shows exactly where in the flow it died.

What comes in the package

• scripts/force-oauth-challenge.py — reference implementation of the fix: forces the WWW-Authenticate and the authorization flow
• references/checklist.md — one-page checklist with the expected value at each diagnostic step

Requirements

• Python 3.10+ (stdlib only)
• access to the MCP server origin
• the /.well-known/* the server itself announces

Where it does not fit: This is for MCP servers with OAuth — a public tool returns 200 and the skill tells you to pick another one. It buys and pays nothing: if the server asks for payment, it stops and hands the decision back to the owner.

Prices in Brazilian real (BRL). Stripe charges in BRL.

← all skills