setting_sources=[] does not filter OAuth-fetched claude.ai-account MCP servers

[brandonrdug]

Observation

ClaudeAgentOptions(setting_sources=[]) is commonly understood as the one-stop filter for an isolated harness — it blocks user/project/local settings, agents, skills, and plugins from loading. But it does not filter claude.ai-account MCP servers fetched via OAuth (Figma, Gmail, Calendar, Drive — whichever MCPs the operator has provisioned on their claude.ai account).

Result: an isolated test harness using setting_sources=[] + explicit plugins=[...] still pulls in the operator's account MCPs on every run. Symptoms are noisy stderr debug lines ([claudeai-mcp] Fetching from https://api.anthropic.com/v1/mcp_servers?limit=1000), diagnostic contamination when comparing MCP surfaces across test runs, and slower init.

Repro

from claude_agent_sdk import ClaudeAgentOptions, query

options = ClaudeAgentOptions(
    setting_sources=[],
    plugins=[],
    mcp_servers={},  # explicitly empty
    permission_mode="bypassPermissions",
    model="claude-opus-4-7",
    max_turns=1,
    extra_args={"debug-to-stderr": None},
)

async for msg in query(prompt="hi", options=options):
    pass

On a subscription account with any claude.ai MCPs provisioned, the stderr shows [claudeai-mcp] Fetching... followed by each MCP being connected, despite mcp_servers={} and setting_sources=[].

Workaround

Add --strict-mcp-config via extra_args:

extra_args={"debug-to-stderr": None, "strict-mcp-config": None}

This restricts the CLI to MCP servers declared in mcp_servers. Works, but requires knowing the CLI flag exists — it is not documented alongside setting_sources in the SDK README or docstring.

What would close this

Either path would land the fix:

Docs-only: Clarify in the ClaudeAgentOptions docstring (and the SDK README "Isolation" section, if one exists) that setting_sources=[] does not suppress OAuth-fetched MCPs, and document extra_args={"strict-mcp-config": None} as the companion lever for complete MCP isolation.

Behavior: Treat setting_sources=[] as opting out of all ambient operator environment, including OAuth-fetched account MCPs — semantically consistent with "filter everything from the operator's setup." If a caller wants account MCPs back, they pass a non-empty setting_sources.

Docs-only is the lower-risk path and unblocks users writing test harnesses today. The behavior change is cleaner long-term but affects anyone who currently relies on the cross-cutting behavior.

Environment

• claude-agent-sdk 0.1.63
• claude CLI 2.1.114 (bundled)
• Python 3.12, Linux
• Subscription auth (Pro/Max) via claude login

Context

Surfaced while building an end-to-end test harness for a local tool (projectmeta). Full context: https://github.com/brandonrdug/projectmeta/issues/102 and mitigation landed in https://github.com/brandonrdug/projectmeta/pull/100. The --strict-mcp-config workaround is working well in production; the ask here is a docs fix (or behavior tweak) so the next person doesn't have to rediscover it.