MCP: Manual .mcp.json edits not recognized, and 'claude mcp add' overwrites existing servers

Environment

• Claude Code version: 2.0.60
• OS: macOS (Darwin 24.6.0)

Description

Two related issues with MCP server configuration:

Issue 1: Manual .mcp.json edits not recognized

When manually adding a new MCP server to .mcp.json, Claude Code does not recognize the new server.

Steps to reproduce:

1. Have existing MCP servers configured via claude mcp add
2. Manually edit .mcp.json to add a new server (e.g., context7)
3. Restart Claude Code
4. Run claude mcp list

Expected: The manually added server appears in the list
Actual: Only previously added servers appear; the manually added one is missing

Root cause: Claude Code uses ~/.claude.json (projects.<path>.mcpServers) as the source of truth, not .mcp.json directly. Manual edits to .mcp.json are not synced.

Issue 2: claude mcp add overwrites existing .mcp.json

When running claude mcp add or claude mcp add-json, the command overwrites .mcp.json instead of merging with existing servers.

Steps to reproduce:

1. Have multiple servers in .mcp.json
2. Run claude mcp add newserver ...
3. Check .mcp.json

Expected: New server is added alongside existing ones
Actual: .mcp.json is overwritten with only the new server

Issue 3: HTTP server headers cannot be set via CLI

For HTTP-type MCP servers requiring authentication headers, there's no CLI option to set them.

Workaround: Manually edit .mcp.json after adding via CLI (but this conflicts with Issue 1)

# This works but doesn't support headers
claude mcp add --transport http mapify 'https://example.com/mcp' -s project

# Need to manually add headers afterward

Expected Behavior

1. Either .mcp.json should be the source of truth (synced to internal config), or the documentation should clearly state to never manually edit it
2. claude mcp add should merge with existing servers, not overwrite
3. CLI should support setting headers for HTTP servers: --header 'Authorization: Bearer xxx'

Workaround

Add all servers via claude mcp add commands sequentially, then manually edit .mcp.json for headers if needed.

🤖 Generated with Claude Code