Pit record
Claude Agent SDK does not load .mcp.json unless settingSources includes "project"
Launching the Claude Agent SDK from a directory with .mcp.json may show no MCP servers (mcpServerStatus()/mcp_servers empty) because the SDK does not read filesystem settings by default. Pass settingSources including 'project'. An older bug also required a prior CLI run in the cwd; that was fixed in a later release.
Markdown mirror | Canonical source
Fast answer
Problem: the SDK reports no MCP servers even though .mcp.json is in the working directory
Root cause: The Agent SDK does not auto-load project/user/local settings from disk; it loads them only when settingSources is set.
Fix first: Pass settingSources including 'project' (and 'user'/'local' as needed) when constructing the SDK query so .mcp.json is read.
Verify: Inspect mcpServerStatus() / the mcp_servers field on first SDK launch.
Queries this answers
- SDK doesnt read from .mcp.json until the CLI is run in the cwd
- SDK doesnt read from .mcp.json until the CLI is run in the cwd fix
- SDK doesnt read from .mcp.json until the CLI is run in the cwd root cause
- Claude Agent SDK does not load .mcp.json unless settingSources includes project
- Claude Agent SDK does not load .mcp.json unless settingSources includes "project" fix
- Claude Agent SDK does not load .mcp.json unless settingSources includes "project" root cause
- how to fix Claude Agent SDK does not load .mcp.json unless settingSources includes project
- claude-code load mcp json unless settingsources includes project
Record metadata
| Status | verified |
|---|---|
| Confidence | high |
| Created | 2026-06-21 |
| Updated | 2026-06-21 |
| Last verified | 2026-06-21 |
| Affected tools | claude-code, claude-agent-sdk |
| Tags | mcp, claude-agent-sdk, claude-code, mcp-json, settings, configuration |
Common search queries
- claude-agent-sdk-mcp-json-requires-project-settingsource
- claude agent sdk mcp json requires project settingsource
- Claude Agent SDK does not load .mcp.json unless settingSources includes project
- Claude Agent SDK does not load .mcp.json unless settingSources includes "project" fix
- Claude Agent SDK does not load .mcp.json unless settingSources includes "project" root cause
- claude-agent-sdk
- claude-code
- mcp-json
- settings
- configuration
- the SDK reports no MCP servers even though .mcp.json is in the working directory
- servers appear only after launching the claude CLI in the same directory and running /mcp, then restarting the SDK process
Symptoms
- the SDK reports no MCP servers even though .mcp.json is in the working directory
- servers appear only after launching the claude CLI in the same directory and running /mcp, then restarting the SDK process
- tools wrapping Claude (e.g. Conductor) cannot see project MCP servers
Environment
| runtime | Node.js / Claude Agent SDK |
|---|---|
| agent | claude-agent-sdk |
| constraints | SDK loads settings only when settingSources is configured |
Root cause
- The Agent SDK does not auto-load project/user/local settings from disk; it loads them only when settingSources is set.
- Without 'project' in settingSources, .mcp.json is ignored.
- A separate SDK bug required a prior CLI run in the cwd before project MCP servers were discovered; this was fixed in a release.
Fix
Pass settingSources including 'project' (and 'user'/'local' as needed) when constructing the SDK query so .mcp.json is read.
Upgrade to a Claude Code / Agent SDK release that fixed the cwd-only discovery bug.
Confirm the working directory actually contains the intended .mcp.json.
Verification
Inspect mcpServerStatus() / the mcp_servers field on first SDK launch.
Expected: Lists the .mcp.json servers without first running the CLI in that directory.
Workarounds
- Define MCP servers programmatically via the SDK options if you cannot rely on filesystem settings.
Anti-patterns
- Expecting the Agent SDK to auto-load .mcp.json like the interactive CLI, without setting settingSources.
- Launching the CLI once per directory as a workaround instead of configuring settingSources.
Sources
No matching fix?
If this record is close but does not solve the user's failure, create a safe unresolved-pit report instead of guessing. Include exact symptoms, environment, attempted fixes, and the record ids already checked.