KBCodeKB
Claude CodeUnverified

Fix Claude Agent SDK Not Reading .mcp.json Project-Scoped MCP Servers on First Startup — MCP Tools Missing in CI/CD, Conductor, and Automated Workflows

The Claude Agent SDK fails to load project-scoped MCP server configurations from .mcp.json on initial startup. When using query() via the SDK, MCP tools defined in the project's .mcp.json are silently absent — mcpServerStatus() returns empty and SDKSystemMessage.mcp_servers is unpopulated. Local and user-scoped MCP configurations work correctly; only project-scoped MCPs are affected. The bug blocks SDK-based automation tools like Conductor (conductor.build) from accessing project MCP tools until the CLI is manually launched in the same directory. Anthropic staff (ollie-anthropic) confirmed the fix shipped in v2.0.71 (Dec 16, 2025). Impact: 73 community reactions across SDK automation users.

Symptoms

  • mcpServerStatus() callback returns empty or missing project-scoped MCP servers on first SDK startup
  • SDKSystemMessage.mcp_servers field is empty when query() is called before CLI launch
  • MCP tools defined in project .mcp.json are unavailable to SDK query() calls
  • MCP tools only appear after manually launching `claude` CLI from the same working directory and running /mcp
  • Local and user-scoped MCP servers work correctly — only project-scoped MCPs are affected
  • SDK-based automation tools (Conductor, CI/CD pipelines) cannot access project MCP tools

Possible causes

  • Claude Agent SDK initialization path omits project-scoped .mcp.json file discovery — the SDK only reads local (~/.claude/) and user-scoped MCP configurations during startup
  • The CLI launch triggers a side effect (working directory registration or MCP cache population in ~/.claude/) that the SDK subsequently picks up, masking the underlying SDK initialization gap
  • Project-scoped MCP resolution relies on CLI-specific code paths not shared with the SDK module, creating a divergence between CLI and SDK MCP loading behavior
  • The settingSources configuration option (which controls whether 'project' settings are loaded) may not propagate correctly from SDK instantiation to the MCP subsystem

Solutions

Explicit settingSources Configuration + Upgrade

risk: lowagentpublished

Ensure the SDK is configured with `settingSources: ["project"]` alongside the v2.0.71+ upgrade. This explicitly enables project-scoped configuration loading, providing defense-in-depth against future regressions.

  1. Upgrade to v2.0.71+: `npm install -g @anthropic-ai/claude-code@latest`
  2. In your SDK initialization code, add `settingSources: ["user", "project", "local"]` to the options object
  3. Verify project-scoped settingSources is documented: https://platform.claude.com/docs/en/agentsdk/configuration
  4. Test with a .mcp.json file in the project directory

Commands

npm install -g @anthropic-ai/claude-code@latest
grep -r 'settingSources' /path/to/sdk/init.js

Config examples

{
  "settingSources": ["user", "project", "local"],
  "cwd": "/path/to/project"
}

Risks

  • settingSources configuration is only effective on v2.0.71+ — earlier versions ignore it for project-scoped MCP
  • Setting 'project' as a source may load other project-scoped settings (CLAUDE.md, rules) that could change behavior

Verification

  • Step 1: Add `settingSources: ["user", "project", "local"]` to SDK initialization → expect: SDK starts without errors
  • Step 2: Call mcpServerStatus() from SDK → expect: project-scoped MCP servers present in the list
  • Step 3: Run query() and check SDKSystemMessage → expect: mcp_servers field populated
✓ 0 verified✕ 0 failed

Pre-Launch CLI Workaround (for Versions < 2.0.71)

risk: lowhumanpublished

If upgrading is not immediately possible, launch the Claude CLI once in the working directory before starting the SDK. The CLI initializes the MCP cache, which the SDK can then read. This is a temporary workaround until upgrade.

  1. Navigate to the project directory containing .mcp.json
  2. Run `claude --print " "` to launch the CLI, initialize MCP cache, and exit immediately
  3. Start the Claude Agent SDK process
  4. Verify MCP tools are now available via mcpServerStatus()

Commands

cd /path/to/project && claude --print " " && exit
claude --print " " 2>/dev/null; echo 'CLI init complete'

Risks

  • Requires CLI to be installed and accessible in the automation environment
  • Adds startup latency to SDK initialization (CLI launch overhead)
  • CLI may prompt for authentication or updates — use --print flag to minimize interaction

Verification

  • Step 1: Before CLI launch, call mcpServerStatus() from SDK in project directory → expect: empty or missing project MCP servers
  • Step 2: Run `claude --print " "` in the project directory → expect: CLI exits cleanly (exit code 0)
  • Step 3: Restart SDK and call mcpServerStatus() again → expect: non-empty server list with project-scoped MCP servers now present
✓ 0 verified✕ 0 failed

Upgrade to Claude Code v2.0.71+ (Official Fix — Recommended)

risk: lowofficialpublished

Anthropic fixed the SDK's project-scoped .mcp.json loading in v2.0.71 (Dec 16, 2025). Upgrading resolves the issue permanently — the SDK will read .mcp.json from the working directory on first startup without requiring a CLI pre-launch.

  1. Upgrade Claude Code to v2.0.71 or later: `npm install -g @anthropic-ai/claude-code@latest`
  2. Verify the installed version: `claude --version` → expect: 2.0.71 or higher
  3. Restart any running SDK processes or automation tools (Conductor, CI/CD pipelines)
  4. Run query() from the SDK in a directory containing .mcp.json — MCP tools should now be available without a CLI pre-launch

Commands

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

Risks

  • Upgrading may introduce other behavioral changes — test in a staging environment first
  • If using pinned versions in CI/CD, update version constraints in package.json or Dockerfile

Verification

  • Step 1: Create a test .mcp.json in a working directory with a simple MCP server definition → expect: file exists at project root
  • Step 2: Launch the Claude Agent SDK from that directory and call mcpServerStatus() → expect: non-empty server list including the project-scoped MCP server
  • Step 3: Run query() and inspect SDKSystemMessage.mcp_servers in the response → expect: field populated with project-scoped MCP server entries
  • Step 4: Run `npm view @anthropic-ai/claude-code version` → expect: 2.0.71 or higher
✓ 0 verified✕ 0 failed

Agent JSON

Canonical machine-readable representation of this issue:

{
  "issue_id": "48130631-0eb5-4d5b-9c1c-f08a38eab52b",
  "slug": "fix-claude-agent-sdk-not-reading-mcp-json-project-scoped-mcp-servers-on-first-startup-mcp-tools-missing-in-ci-cd-conduct-bdujzx",
  "verification_status": "unverified",
  "canonical_json": "https://codekb.dev/v1/issues/fix-claude-agent-sdk-not-reading-mcp-json-project-scoped-mcp-servers-on-first-startup-mcp-tools-missing-in-ci-cd-conduct-bdujzx"
}
← Back to all issuesPowered by CodeKB