Project-scoped MCP servers don't trigger approval prompt

[cfdude]

Bug Report: Project-scoped MCP servers don't trigger approval prompt

Summary

When starting a Claude Code session in a project containing .mcp.json, the expected approval prompt for project-scoped MCP servers never appears. Users must manually create .claude/settings.local.json to enable servers, bypassing the intended security workflow.

Expected Behavior

1. Start Claude Code session in project with .mcp.json
2. Approval prompt appears: "This project wants to use MCP servers: [list]. Approve?"
3. On approval, .claude/settings.local.json is automatically created with enabled servers
4. Servers become available in /mcp

Actual Behavior

1. Start Claude Code session in project with .mcp.json ✅
2. No approval prompt appears ❌
3. .claude/settings.local.json is NOT created ❌
4. Servers do NOT appear in /mcp list ❌
5. Must manually create .claude/settings.local.json with enabledMcpServers array

Steps to Reproduce

1. Create project directory
2. Add .mcp.json with MCP server configurations:

{
  "mcpServers": {
    "google-workspace": {
      "command": "uv",
      "args": ["--directory", "/path/to/server", "run", "main.py"],
      "env": { ... }
    }
  }
}

3. Start Claude Code session in project: claude code
4. Expected: Approval prompt appears
5. Actual: No prompt, servers not available

Observed Issues

• claude mcp list does NOT show project-scoped servers from .mcp.json
• No approval prompt at session start
• No indication that .mcp.json was even detected
• Possible conflict when same-named servers exist in user-scoped config

Environment

• OS: macOS Darwin 25.0.0
• Claude Code CLI (latest)
• .mcp.json exists in project root with valid configuration

Workaround

Manually create .claude/settings.local.json:

{
  "enabledMcpServers": ["google-workspace", "mcp-datetime"]
}

Impact

• Breaks documented security model for project-scoped MCP servers
• Users unaware of .claude/settings.local.json requirement
• No visibility into which servers are project vs user-scoped
• Approval mechanism completely non-functional

Suggested Fixes

1. Critical: Trigger approval prompt on session start when .mcp.json detected
2. Add --verbose flag to show MCP server discovery/loading process
3. Show scope indicators in claude mcp list (user/project/local)
4. Warn when project servers conflict with user-scoped servers
5. Document .claude/settings.local.json approval mechanism clearly

[cfdude]

Update: Workaround confirmed working + documentation issue

After further investigation, the manual workaround does work, but the required .claude/settings.local.json structure is undocumented. The correct format is:

{
  "permissions": {
    "allow": [
      "mcp__server-name__*"
    ],
    "deny": []
  },
  "enableAllProjectMcpServers": true,
  "enabledMcpjsonServers": [
    "server-name"
  ]
}

Key findings:

1. Property is enabledMcpjsonServers (not enabledMcpServers)
2. Requires enableAllProjectMcpServers: true flag
3. Requires permissions.allow array with mcp__<server-name>__* pattern
4. Name conflicts: Project-scoped servers with same names as user-scoped servers are completely ignored (recommend using unique names like server-name-local)

After restart with correct .claude/settings.local.json structure, project-scoped servers now appear in /mcp list.

Core bug remains: No approval prompt appears on session start - users must manually create this file with the correct (undocumented) structure.

[github-actions]

Found 3 possible duplicate issues:

1. [BUG] v1.0.98 is not reading project .mcp.json and rewriting .claude/settings.local.json #6855
2. [BUG] .mcp.json is not read #3321
3. .mcp.json file is not being loaded #1313

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[rboyce-ant]

Can you run /doctor from Claude Code in this project? When we've seen this before, it was a parsing issue from an invalid settings.json file.

[cfdude]

I ran /doctor in this project and don't have any reported issues. Mind you I experienced this bug when there was no settings.json file in existence - Claude Code never created one in this project folder when I first used the claude command in the terminal. I think the only thing that may be different is the first time I initiated this session for the first time I did 'claude --dangerously-skip-permissions'

[clouatre]

Can confirm this issue. Through systematic testing of both official methods:

Test 1: Official CLI method

• Used claude mcp add --scope project to add servers
• Started claude code session in project directory
• Result: ❌ No approval prompt appeared, servers not loaded, /mcp showed "No MCP servers configured"

Test 2: Official manual .mcp.json method

• Manually created .mcp.json with three MCP server configurations (HTTP, SSE, stdio transports)
• Started claude code session in project directory
• Result: ❌ No approval prompt appeared, servers not loaded, /mcp showed "No MCP servers configured"

Test 3: Applied workaround from this issue

• Created [project]/.claude/settings.local.json with minimal configuration:

{
  "permissions": {
    "allow": ["mcp__*"]
  },
  "enableAllProjectMcpServers": true
}

• Restarted claude code session
• Result: ✅ All three servers loaded successfully and functional

Tested variations of workaround:

• enableAllProjectMcpServers: true + explicit enabledMcpjsonServers array → works
• enableAllProjectMcpServers: true + wildcard permissions only → works (more maintainable)

Both official methods documented at https://docs.claude.com/en/docs/claude-code/mcp#project-scope fail - manual workaround required.

Environment: macOS 26.0.1, Claude Code v2.0.27