Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] Agent SDK MCP docs omit `mcp_authenticate` `redirectUri` usage for custom schemes and Claude.ai connectors [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#54171•Fetched 2026-04-29 06:34:23
View on GitHub
Comments
0
Participants
1
Timeline
5
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeek
Timeline (top)
labeled ×5
RAW_BUFFERClick to expand / collapse

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:

PageContext
https://code.claude.com/docs/en/agent-sdk/mcpPrimary Agent SDK MCP authentication documentation
https://platform.claude.com/docs/en/agent-sdk/mcpAgent 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

extent analysis

TL;DR

Update the OAuth2 authentication section in the Agent SDK MCP guide to document the SDK-native authentication flow using mcp_authenticate and its redirectUri parameter.

Guidance

  • Review the changelog entry for v2.1.121 to understand the new mcp_authenticate functionality and its support for redirectUri.
  • Add a subsection for mcp_authenticate in the OAuth2 authentication section to explain its purpose and usage.
  • Document the redirectUri parameter, including when to use it for custom scheme completion and Claude.ai connectors.
  • Provide examples for custom-scheme redirect completion and clarify the difference between using mcp_authenticate and manually supplying Authorization headers.

Example

No code snippet is provided as the issue focuses on documentation updates rather than code changes.

Notes

The suggested improvements aim to clarify the authentication flow for users, reducing confusion and making the feature easier to understand. The updates should be applied to both affected pages.

Recommendation

Apply workaround: Update the documentation to reflect the correct usage of mcp_authenticate and its redirectUri parameter, as this will improve the user experience and provide accurate guidance for authentication flows.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#permission error#memory optimization#batch processing#GPU compatibility#latency issue

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING