Unverified

Fix Claude Agent SDK Not Reading .mcp.json Project-Scoped MCP Servers (v2.0.71+) — Conductor, CI/CD, and Non-Interactive Environments

The Claude Agent SDK (`query()` function) does not read project-scoped MCP servers from `.mcp.json` on startup, even with `settingSources: ['project']`. MCP servers only become available after manually launching `claude` CLI, running `/mcp`, then restarting the SDK. This blocks all non-interactive environments including CI/CD pipelines and automation platforms like Conductor. User-scoped and local-scoped MCPs load correctly — only project-scoped `.mcp.json` is affected. Fix shipped in v2.0.71 (December 16, 2025), confirmed by Anthropic staff assignee ollie-anthropic: 'this should be fixed in the latest release coming out today.'

Symptoms

`mcpServerStatus()` callback returns empty or missing project-scoped MCP servers when called from Agent SDK
`SDKSystemMessage.mcp_servers` field is empty or missing project-configured servers on initial SDK query() calls
Project-scoped `.mcp.json` MCP servers only appear after manually launching `claude` CLI and running `/mcp`, then restarting the SDK
User-scoped and local-scoped MCPs load correctly — only project-scoped (`.mcp.json` in working directory) are affected
Automation platforms like Conductor cannot access project MCP servers without manual CLI intervention

Possible causes

The Agent SDK's initialization path for project-scoped MCP configurations differs from the CLI's path. The CLI eagerly loads `.mcp.json` when launched in a directory, but the SDK's `query()` function skips this step
The `settingSources` option with `'project'` is correctly passed to the SDK, but the SDK's MCP server discovery logic does not scan the working directory's `.mcp.json` until the CLI has previously cached or registered the project configuration
This is an initialization ordering issue: the SDK's MCP loading code path was designed around the CLI-first workflow and assumed project MCP configurations would already be registered before SDK usage

Solutions

Use User-Scoped MCP Configuration Instead of Project-Scoped (Universal Workaround)

risk: lowagentpublished

Move your MCP server configuration from project-scoped `.mcp.json` to user-scoped `~/.claude/.mcp.json`, which is loaded correctly by the SDK on initialization regardless of version.

Copy your project `.mcp.json` MCP server definitions
Merge them into user-scoped config: `~/.claude/.mcp.json` (create if it doesn't exist)
Ensure SDK `settingSources` includes `'user'`: `const options = { settingSources: ['user', 'project', 'local'] }`
Restart your SDK — user-scoped MCPs load immediately without CLI warm-up

Commands

cat .mcp.json

mkdir -p ~/.claude

cat .mcp.json >> ~/.claude/.mcp.json

Config examples

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@scope/my-mcp-server"]
    }
  }
}

Risks

User-scoped MCPs apply to ALL projects — may cause conflicts with project-specific server configurations
Not suitable for team-shared `.mcp.json` that needs version control
Upgrading to v2.0.71+ is the proper long-term solution

Verification

Step 1: Run `cat ~/.claude/.mcp.json 2>&1 | python3 -m json.tool > /dev/null; echo exit=$?` → expect: exit code 0 (valid JSON). If exit code is non-zero, fix JSON syntax in the file.
Step 2: Start SDK and call `mcpServerStatus()` immediately → expect: user-scoped MCP servers are listed without any prior CLI interaction
Step 3: Verify NO CLI warm-up was performed: confirm you did NOT run `claude` or `/mcp` before the SDK call

✓ 0 verified✕ 0 failed

Workaround: Warm Up MCP Configuration via CLI Before SDK Usage (Pre-v2.0.71)

risk: lowgithubpublished

If you cannot upgrade from a pre-v2.0.71 version, launch `claude` CLI in the project directory and run `/mcp` to register project-scoped MCP servers before starting your SDK process. This caches the `.mcp.json` configuration so the SDK can discover it.

Navigate to your project directory: `cd /path/to/project`
Launch Claude Code CLI: `claude`
Run `/mcp` to trigger MCP server discovery — you should see your `.mcp.json` servers listed
Exit Claude Code CLI (type `/exit` or Ctrl+C)
Start your SDK application — project-scoped MCPs should now be available on `query()`

Commands

cd /path/to/project && claude

# In Claude CLI, run: /mcp

# Then exit: /exit

Risks

This is a manual one-time warm-up per project directory — does not survive environment changes or `.mcp.json` edits
Automation platforms (Conductor, CI/CD) cannot use this workaround as it requires interactive CLI access
Plan to upgrade to v2.0.71+ as soon as possible

Verification

Step 1: Run `ls .mcp.json 2>&1; echo exit=$?` in your project directory → expect stdout: '.mcp.json', exit code 0. If exit code is non-zero, `.mcp.json` is missing — create it first.
Step 2: Launch `claude` and run `/mcp` → expect: MCP servers from `.mcp.json` appear in the listed output
Step 3: Exit CLI, start SDK, and call `mcpServerStatus()` → expect: project servers now appear in the returned list

✓ 0 verified✕ 0 failed

Upgrade Claude Code to v2.0.71 or Later (Official Fix — Confirmed by Anthropic Staff)

risk: lowofficialpublished

Anthropic fixed the Agent SDK project-scoped MCP loading in v2.0.71 (December 16, 2025). The SDK now reads `.mcp.json` on initialization without requiring a CLI warm-up step. Confirmed by ollie-anthropic (Anthropic staff) who closed the issue.

Check your current Claude Code version: `claude --version`
If version is below 2.0.71, upgrade: `npm install -g @anthropic-ai/claude-code@latest`
Verify the upgrade: `npm view @anthropic-ai/claude-code version`
Restart your SDK application — project-scoped MCPs should now be available immediately on first `query()` call

Commands

claude --version

npm install -g @anthropic-ai/claude-code@latest

npm view @anthropic-ai/claude-code version

Risks

Upgrading from a very old version (pre-2.0.71) may introduce breaking changes — test in a staging environment first
Ensure `settingSources` still includes `'project'`: verify with `console.log(options.settingSources)`

Verification

Step 1: Run `claude --version 2>&1; echo exit=$?` → expect stdout contains version ≥ 2.0.71 (e.g., '2.1.177'), exit code 0. If exit code is non-zero, abort — Claude Code is not installed.
Step 2: Run `npm view @anthropic-ai/claude-code version` → expect stdout: '2.1.177' or later (latest as of June 2026). If version is below 2.0.71, run `npm install -g @anthropic-ai/claude-code@latest` first.
Step 3: In your SDK initialization code, verify `settingSources` includes `'project'`: add `console.log(JSON.stringify(options.settingSources))` → expect stdout contains '"project"'
Step 4: Call `mcpServerStatus()` immediately after SDK `query()` initialization (before any CLI interaction) → expect: project-scoped MCP servers from `.mcp.json` are present in the returned list
Step 5: Send a message via `query()` and inspect `SDKSystemMessage` events for `mcp_servers` field → expect: project-configured servers are listed without requiring a prior `claude` CLI launch

✓ 0 verified✕ 0 failed

Agent JSON

Canonical machine-readable representation of this issue:

{
  "issue_id": "f0963967-5d50-457d-8423-28db3b3a4ae1",
  "slug": "fix-claude-agent-sdk-not-reading-mcp-json-project-scoped-mcp-servers-v2-0-71-conductor-ci-cd-and-non-interactive-environ-8xjs4m",
  "verification_status": "unverified",
  "canonical_json": "https://codekb.dev/v1/issues/fix-claude-agent-sdk-not-reading-mcp-json-project-scoped-mcp-servers-v2-0-71-conductor-ci-cd-and-non-interactive-environ-8xjs4m"
}