Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix Background subagents cannot access OAuth-authenticated MCP servers [3 comments, 3 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#46228•Fetched 2026-04-11 06:25:46
View on GitHub
Comments
3
Participants
3
Timeline
8
Reactions
0
Author
RLGN7546RLGN7546
Participants
github-actions[bot]github-actions[bot]RLGN7546RLGN7546shigechikashigechika
Timeline (top)
labeled ×5commented ×3

Root Cause

Each subagent process establishes its own MCP connection. For OAuth-protected servers, this connection is unauthenticated because:

  • OAuth tokens appear to be held in-memory per transport connection
  • No shared token store exists between parent and child processes
  • The authenticate tool (which triggers interactive browser flow) is the only tool exposed to the subagent

Fix Action

Workaround

We use Playwright MCP to drive the OAuth consent flow from within the subagent (4-click automated re-auth using persistent browser profile with saved Google session cookies). This works but adds complexity and latency.

RAW_BUFFERClick to expand / collapse

Preflight Checklist

  • I have searched existing issues and this hasn't been reported yet
  • This is a single bug report (please file separate reports for different bugs)
  • I am using the latest version of Claude Code

What's Wrong?

Background subagents spawned via the Agent tool cannot access MCP servers that require OAuth authentication. The parent session completes the OAuth flow and holds a valid token, but spawned agents start fresh connections without the authenticated session. This forces subagents to either skip OAuth-dependent tools entirely or attempt a full re-auth flow (e.g., via Playwright automation), adding 15-30 seconds of overhead per agent.

Affected MCP types:

  • HTTP MCP servers with OAuth (e.g., Superhuman Mail at https://mcp.mail.superhuman.com/mcp)
  • Built-in claude.ai connectors (e.g., mcp__claude_ai_Gmail__*) — these also require interactive /mcp auth and don't propagate to subagents

Not affected:

  • stdio MCP servers (e.g., local Node.js servers via command/args) — these work fine in subagents
  • SSE MCP servers on localhost (e.g., Obsidian, custom bots) — these work fine

Environment

  • Claude Code version: 2.1.87
  • OS: macOS 13.6.9 (Darwin 22.6.0)
  • Subscription: Max plan
  • MCP config: Project-level .claude/.mcp.json with HTTP and SSE servers

Steps to Reproduce

  1. Configure an HTTP MCP server requiring OAuth (e.g., Superhuman Mail)
  2. Authenticate via /mcp in the main session — tools become available
  3. Spawn a background agent: Agent({ run_in_background: true, prompt: "Use mcp__superhuman-mail__list_threads to get recent emails" })
  4. The subagent receives authorization errors or only finds the authenticate tool

Expected Behavior

Subagents spawned from an authenticated parent session should inherit or share the parent's MCP OAuth tokens. The token is already valid — the subagent just can't access it.

Actual Behavior

Each subagent process establishes its own MCP connection. For OAuth-protected servers, this connection is unauthenticated because:

  • OAuth tokens appear to be held in-memory per transport connection
  • No shared token store exists between parent and child processes
  • The authenticate tool (which triggers interactive browser flow) is the only tool exposed to the subagent

Workaround

We use Playwright MCP to drive the OAuth consent flow from within the subagent (4-click automated re-auth using persistent browser profile with saved Google session cookies). This works but adds complexity and latency.

Proposed Solutions (in order of preference)

  1. Token inheritance: Pass the parent's OAuth token to subagent processes via environment variable or shared credential file
  2. Shared token store: Persist OAuth tokens to a file-based store (e.g., ~/.claude/mcp-tokens.json) readable by all Claude Code processes in the same user session
  3. MCP proxy: Parent process acts as an MCP proxy, forwarding subagent tool calls through its authenticated connection

Related Issues

  • #24317 — OAuth refresh token race condition with concurrent sessions (related but distinct: that's about token invalidation across parallel sessions; this is about token absence in child processes)
  • #43397 — Cloud scheduled tasks can't access MCP connectors (same class of problem in cloud context)

extent analysis

TL;DR

Implementing token inheritance or a shared token store can likely resolve the issue of subagents being unable to access OAuth-protected MCP servers.

Guidance

  • Investigate passing the parent's OAuth token to subagent processes via an environment variable to maintain authentication across processes.
  • Consider implementing a shared token store, such as a file-based store, to persist OAuth tokens and make them accessible to all Claude Code processes in the same user session.
  • Evaluate the feasibility of using an MCP proxy, where the parent process forwards subagent tool calls through its authenticated connection, as a potential workaround.
  • Review related issues, such as #24317 and #43397, to understand the broader context of OAuth token management in Claude Code.

Example

// Example of passing OAuth token as an environment variable
const token = getParentOAuthToken();
process.env.MCP_OAUTH_TOKEN = token;

Notes

The proposed solutions require careful consideration of security implications, such as token storage and transmission. Additionally, the implementation details may vary depending on the specific requirements and constraints of the Claude Code system.

Recommendation

Apply a workaround, such as token inheritance or a shared token store, to address the immediate issue of subagents being unable to access OAuth-protected MCP servers. This approach allows for a more straightforward and targeted solution compared to upgrading to a potentially non-existent fixed version.

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…
#docker error#permission error#memory optimization#batch processing#environment variable

Still need to ship something?

×6

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

Back to top recommendations

TRENDING