claude-code - 💡(How to fix) Fix [DOCS] MCP OAuth docs omit `client_secret_post` support for pre-configured credentials [1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/mcp#use-pre-configured-oauth-credentials

Section/Topic

Use pre-configured OAuth credentials for MCP servers, plus the related MCP_CLIENT_SECRET environment variable reference.

Current Documentation

The docs currently say:

Some MCP servers don't support automatic OAuth setup via Dynamic Client Registration. If you see an error like "Incompatible auth server: does not support dynamic client registration," the server requires pre-configured credentials. Claude Code also supports servers that use a Client ID Metadata Document (CIMD) instead of Dynamic Client Registration, and discovers these automatically. If automatic discovery fails, register an OAuth app through the server's developer portal first, then provide the credentials when adding the server.

Use --client-id to pass your app's client ID. The --client-secret flag prompts for the secret with masked input:

• The client secret is stored securely in your system keychain (macOS) or a credentials file, not in your config

The env var reference also says:

MCP_CLIENT_SECRET — OAuth client secret for MCP servers that require pre-configured credentials. Avoids the interactive prompt when adding a server with --client-secret

What's Wrong or Missing?

These pages explain how to supply and store a client secret, but they do not document that Claude Code uses that stored secret during the OAuth token exchange for servers that require client_secret_post token-endpoint authentication.

Changelog v2.1.119 makes this supported behavior explicit:

Fixed MCP OAuth client secret stored via --client-secret not being sent during token exchange for servers requiring client_secret_post

Without this detail, users cannot tell whether --client-secret is expected to work with OAuth servers that require client_secret_post, or whether a failed token exchange means the server is unsupported.

Suggested Improvement

Add a short compatibility note in Use pre-configured OAuth credentials stating that Claude Code sends the stored client secret during the OAuth token exchange, including for servers that require client_secret_post.

Also add a brief troubleshooting/version note such as:

client_secret_post support for MCP OAuth token exchange requires Claude Code v2.1.119 or later.

The MCP_CLIENT_SECRET env var entry should cross-reference the same behavior so CI users know the environment variable is used for the token exchange, not just for initial setup.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 2 pages affected

Source: Changelog v2.1.119

Exact changelog entry: Fixed MCP OAuth client secret stored via --client-secret not being sent during token exchange for servers requiring client_secret_post