claude-code - 💡(How to fix) Fix [DOCS] [MCP] OAuth flow for remote servers does not document proxy/mTLS settings compatibility

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/mcp

Section/Topic

"Authenticate with remote MCP servers" section (lines 643–806), specifically the OAuth 2.0 authentication subsections: "Add the server that requires authentication", "Override OAuth metadata discovery", "Restrict OAuth scopes", and "Use dynamic headers for custom authentication".

Current Documentation

The "Authenticate with remote MCP servers" section describes how OAuth 2.0 is used for MCP server authentication, including dynamic client registration, token exchange, and automatic token refresh:

Many cloud-based MCP servers require authentication. Claude Code supports OAuth 2.0 for secure connections. ... Authentication tokens are stored securely and refreshed automatically

The section documents authServerMetadataUrl for routing OAuth discovery through an internal proxy, but does not mention that general HTTP_PROXY/HTTPS_PROXY/NO_PROXY environment variables or CLAUDE_CODE_CLIENT_CERT/CLAUDE_CODE_CLIENT_KEY mTLS certificates apply to the OAuth flow.

The network-config.md page documents proxy environment variables and mTLS certificate configuration, but does not cross-reference to the MCP OAuth authentication section.

What's Wrong or Missing?

A. Proxy environment variables not documented for OAuth flow

HTTP_PROXY, HTTPS_PROXY, and NO_PROXY are not mentioned as applicable to MCP OAuth discovery, dynamic client registration, token exchange, or token refresh. Users behind corporate proxies who configure these variables expect them to work for all HTTP traffic including MCP OAuth, but the docs do not confirm this.

B. mTLS client certificates not documented for OAuth flow

CLAUDE_CODE_CLIENT_CERT and CLAUDE_CODE_CLIENT_KEY (documented in network-config.md) are not mentioned as applicable to the MCP OAuth flow. Enterprise users with mTLS certificates need to know these work for OAuth authentication to remote MCP servers.

C. No cross-reference between network-config and MCP OAuth docs

The proxy and mTLS configuration documentation lives in network-config.md with no mention that it applies to MCP OAuth. The MCP OAuth section does not link to network-config for proxy or mTLS setup.

Suggested Improvement

Add a note or sub-section within "Authenticate with remote MCP servers" (or a linked network-config reference) clarifying that:

1. HTTP_PROXY / HTTPS_PROXY / NO_PROXY are respected for all OAuth HTTP requests (discovery URLs, token endpoints, dynamic client registration) — not just the initial MCP server connection.

2. CLAUDE_CODE_CLIENT_CERT / CLAUDE_CODE_CLIENT_KEY / CLAUDE_CODE_CLIENT_KEY_PASSPHRASE apply to mTLS-authenticated MCP OAuth flows.

3. When using a corporate proxy or mTLS certificates for MCP OAuth, set the variables documented in Network configuration before starting Claude Code.

Example addition to the "Authenticate with remote MCP servers" section or as a new subsection:

### Proxy and mTLS configuration for OAuth

If you are behind a corporate proxy or use mTLS client certificates, configure the standard proxy and certificate environment variables before starting Claude Code. These settings apply to all MCP OAuth HTTP requests including discovery, dynamic client registration, token exchange, and token refresh.

| Variable | Purpose |
|----------|---------|
| `HTTPS_PROXY` / `HTTP_PROXY` | Route OAuth traffic through a proxy |
| `NO_PROXY` | Bypass proxy for specific hosts |
| `CLAUDE_CODE_CLIENT_CERT` | Client certificate for mTLS |
| `CLAUDE_CODE_CLIENT_KEY` | Client private key for mTLS |

See [Network configuration](https://code.claude.com/docs/en/network-config) for full details on proxy and mTLS setup.

Or add this as a cross-reference note in the existing Tips block at line 667–675.

Impact

High - Prevents users from using a feature

Additional Context

Changelog entry (v2.1.133):

Fixed HTTP(S)_PROXY / NO_PROXY / mTLS not being respected for the full MCP OAuth flow including discovery, dynamic client registration, token exchange, and token refresh

Related documentation:

• network-config.md — proxy and mTLS environment variables documented here, but no MCP OAuth cross-reference
• env-vars.md — HTTP_PROXY, HTTPS_PROXY, NO_PROXY, CLAUDE_CODE_CLIENT_CERT, CLAUDE_CODE_CLIENT_KEY documented
• mcp.md lines 643–806 — MCP OAuth flow documented here, but no proxy/mTLS compatibility mentions

Scope: 1 primary page affected (mcp.md), with a cross-reference note in network-config.md to close the gap bidirectionally.