grant_types: authorization_code and refresh_token — Claude MCP custom…

Symptom

Adding your MCP server to Claude as a custom connector (claude.ai: Settings → Connectors → Add custom connector) gets as far as your authorization server's consent step and stops there. Your server refuses the client with something like:

Client document not accepted — https://claude.ai/oauth/mcp-oauth-client-metadata — grant_types: authorization_code and refresh_token

The same server works with clients whose metadata documents list only the code flow and refresh tokens. In the incident this unit comes from, Claude Code's and ChatGPT's documents listed only those two grant types and connected without trouble.

When it happens

• Your authorization server supports Client ID Metadata Documents (CIMD). The client_id is an https URL, and you fetch and validate the JSON document at that URL.
• Your validator (or your dynamic client registration handler, if it applies the same rule) requires every entry in grant_types to be one you support.
• The client's document lists an extra grant type. Claude's document, as it was served on 2026-10-01:

{ "client_id": "https://claude.ai/oauth/mcp-oauth-client-metadata", "client_name": "Claude",
  "redirect_uris": ["https://claude.ai/api/mcp/auth_callback"],
  "grant_types": ["authorization_code", "refresh_token", "urn:ietf:params:oauth:grant-type:jwt-bearer"],
  "response_types": ["code"], "token_endpoint_auth_method": "none" }

The third grant type, urn:ietf:params:oauth:grant-type:jwt-bearer, is what fails an "every grant must be ours" check.

Cause

The validator treated grant_types as "the only grants this client may use here", so an unknown entry was a reason to refuse. A client's metadata document is published once and used against many authorization servers. It lists every grant the client can use, not only the ones your server runs. The original check:

const grants = Array.isArray(d.grant_types) ? d.grant_types : ["authorization_code"];
if (!grants.every((g) => g === "authorization_code" || g === "refresh_token"))
  return bad("grant_types: authorization_code and refresh_token");

Fix

Require the grant your server actually runs (the authorization code flow). Keep only the grants you support, and quietly drop the rest. Don't refuse the client over them:

// The code flow is what this server runs, so a client must name it; other grant types
// it names are its own business — the token endpoint answers authorization_code and
// refresh_token only, and the rest are not kept.
const declared = Array.isArray(d.grant_types) ? d.grant_types : ["authorization_code"];
if (!declared.includes("authorization_code"))
  return bad("grant_types: authorization_code, the code flow this server runs");
const grants = declared.filter((g) => g === "authorization_code" || g === "refresh_token");

Make the same change in dynamic client registration (POST /register) if it shares the rule. A registration that names jwt-bearer as well is accepted and stored with only the two supported grants. A registration without authorization_code is still refused.

Security doesn't change: the token endpoint still decides which grants it serves. Your token endpoint keeps refusing grant types it doesn't implement, exactly as before. The fix only stops refusing the client for listing them.

Verify

1. Fetch the live document and look at what it lists. Documents change, so don't hard-code what you saw once:

curl -s https://claude.ai/oauth/mcp-oauth-client-metadata | python3 -m json.tool

1. Unit-test the validator on that exact shape: accepted, with stored grants ["authorization_code","refresh_token"].
2. Add a negative case: a document whose grant_types lacks authorization_code is refused, and the reason names the code flow.
3. Run the connector flow end to end with a mock CIMD server that serves Claude's shape: consent, then the code exchange, then a refresh.

Notes

• This is a general robustness rule for any metadata the client publishes (grant_types, extra fields). Validate what you depend on: the client_id equals the URL, the redirect URIs, the auth method, and the code flow being present. Treat extra capabilities as information, not as reasons to refuse.
• response_types is different. The code flow needs code, and refusing a document that asks for something else is reasonable.
• Check every client you plan to support against its current document before you submit to a directory. A validator that passed Claude Code and ChatGPT can still refuse claude.ai.
• For context: the server in this incident supports public clients with token_endpoint_auth_method: none (PKCE S256) and private_key_jwt. It advertises client_id_metadata_document_supported: true and lists none among its token endpoint auth methods in its RFC 8414 metadata. Claude chooses CIMD over dynamic registration only when both are there.