[DOCS] Headless and Agent SDK MCP docs do not explain unauthenticated server behavior

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The claude -p / headless MCP guidance, especially the --bare section, the --mcp-config table row, and the note about which built-in commands are unavailable in -p mode.

Current Documentation

The headless guide currently says:

Add --bare to reduce startup time by skipping auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md. Without it, claude -p loads the same context an interactive session would, including anything configured in the working directory or ~/.claude.

Bare mode skips OAuth and keychain reads. Anthropic authentication must come from ANTHROPIC_API_KEY or an apiKeyHelper in the JSON passed to --settings.

Later on the same page, the docs say:

Built-in commands that open an interactive dialog, such as /login, are not available in -p mode.

The MCP docs currently say:

Use /mcp to authenticate with remote servers that require OAuth 2.0 authentication

And the MCP quickstart says:

Select sentry from the list, press Enter, and choose Authenticate. Your browser opens to Sentry's sign-in page. Approve the connection there.

The Agent SDK MCP guide currently says:

The SDK doesn't handle OAuth flows automatically, but you can pass access tokens via headers after completing the OAuth flow in your application:

What's Wrong or Missing?

A. The headless guide never states the actual rule for auth-required MCP servers

The page says non-bare claude -p loads the same MCP context as an interactive session, and separately says built-in interactive dialogs are unavailable in -p. It never joins those facts into explicit guidance for MCP servers that still need browser sign-in. Users cannot tell whether an unauthenticated remote MCP server is supposed to work, fail, or be skipped in headless mode.

B. The /mcp authentication flow is documented as if it were universal

mcp.md and mcp-quickstart.md both teach the interactive /mcp → Authenticate flow, but neither page cross-references headless or Agent SDK mode when describing OAuth-backed servers. That leaves no explicit statement that this browser-driven path is the interactive workflow, not something a claude -p or SDK run can trigger mid-execution.

C. The intended post-fix SDK behavior is not surfaced

The Agent SDK page explains how to pass credentials after your application completes OAuth, but it does not say what the model should see before that happens. The v2.1.183 changelog says Claude Code fixed MCP servers requiring authentication exposing auth-stub tools to the model in headless/SDK mode. The docs should spell out the intended contract: if a server still needs authentication, headless and SDK runs should treat it as unavailable until credentials are supplied, rather than implying that the model can complete authentication on its own.

Suggested Improvement

Add one short cross-surface note that connects the existing auth guidance across headless, mcp, mcp-quickstart, and agent-sdk/mcp.

Suggested content:

1. In headless.md, add a note near --mcp-config / --bare stating that claude -p can only use MCP servers that are already authenticated or that receive static credentials in config. If a remote server still needs browser sign-in, authenticate it in an interactive Claude Code session first.
2. In mcp.md and mcp-quickstart.md, add a short cross-reference near the /mcp Authenticate steps clarifying that this is the interactive auth path, and that headless / Agent SDK surfaces need pre-authenticated or explicitly credentialed servers.
3. In agent-sdk/mcp.md, add one sentence in the OAuth section explaining that unauthenticated servers should be treated as unavailable until the host application completes auth and supplies the resulting credentials.

That would make the v2.1.183 behavior understandable without requiring users to infer it from multiple separate pages.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/headless | 35, 51, 55, 215 | claude -p loads normal MCP config, --mcp-config is available, bare skips OAuth, and interactive dialogs are unavailable, but the page never states the rule for auth-required MCP servers |
| https://code.claude.com/docs/en/mcp | 194, 475-509 | Interactive /mcp OAuth guidance is documented without a headless / SDK limitation note |
| https://code.claude.com/docs/en/mcp-quickstart | 218-230, 285-309 | Quickstart teaches /mcp → Authenticate and 401/403 troubleshooting, but not the headless / SDK expectation |
| https://code.claude.com/docs/en/agent-sdk/mcp | 149, 157, 182, 450-483 | SDK page covers MCP tool permission and bearer-token auth, but not the user-visible behavior of unauthenticated servers in SDK mode |

Total scope: 4 pages affected

Version: Claude Code v2.1.183

Changelog cross-reference: The v2.1.183 changelog currently records this behavior only as a release note: Fixed MCP servers requiring authentication exposing auth-stub tools to the model in headless/SDK mode.