[DOCS] Agent SDK MCP docs omit `mcp_authenticate` `redirectUri` usage for custom schemes and Claude.ai connectors

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/agent-sdk/mcp

Section/Topic

OAuth2 authentication in the Agent SDK MCP guide

Current Documentation

The docs currently say:

### OAuth2 authentication The MCP specification supports OAuth 2.1 for authorization. The SDK doesn't handle OAuth flows automatically, but you can pass access tokens via headers after completing the OAuth flow in your application:

The section then only shows examples that manually inject an already-acquired bearer token into MCP server headers.

What's Wrong or Missing?

Changelog v2.1.121 added: SDK: mcp_authenticate now supports redirectUri for custom scheme completion and claude.ai connectors.

The Agent SDK MCP docs do not explain that mcp_authenticate exists for MCP authentication flows, and they do not document the new redirectUri support for:

1. custom scheme completion, or
2. Claude.ai connectors.

As written, the page implies the only supported SDK pattern is completing OAuth outside the SDK and manually passing a bearer token in headers. That leaves users without guidance for the documented SDK auth helper behavior added in v2.1.121.

Suggested Improvement

Update the OAuth2 authentication section in the Agent SDK MCP guide to document the SDK-native authentication flow.

Suggested additions:

1. Add a short subsection for mcp_authenticate.
2. Document the redirectUri parameter and when to use it.
3. Include an example for custom-scheme redirect completion.
4. Explain how the same flow applies to Claude.ai connectors.
5. Clarify when users should use mcp_authenticate versus manually supplying Authorization headers.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/agent-sdk/mcp | Primary Agent SDK MCP authentication documentation |
| https://platform.claude.com/docs/en/agent-sdk/mcp | Agent SDK cross-reference with the same OAuth2 authentication guidance |

Total scope: 2 pages affected

Source: Changelog v2.1.121

Exact changelog entry: SDK: mcp_authenticate now supports redirectUri for custom scheme completion and claude.ai connectors