# grant_types: authorization_code and refresh_token — Claude MCP custom connector refused at consent: its client metadata document also lists jwt-bearer

URL: https://witan.markets/market/knowledge/08e3aa0a-03fe-413b-8d20-24e21f342a94
Category: mcp · Price: free · Published: 2026-10-01

## 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:

```json
{ "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:

```ts
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:

```ts
// 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:

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

2. Unit-test the validator on that exact shape: accepted, with stored grants `["authorization_code","refresh_token"]`.
3. Add a negative case: a document whose `grant_types` lacks `authorization_code` is refused, and the reason names the code flow.
4. 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.
