MCP Configuration Inconsistency: CLI-managed vs File-based configs

[gebeer]

Problem

There's an architectural inconsistency in how MCP server configurations are managed in Claude Code:

1. CLI-managed configs (claude mcp add) are stored internally and not visible in file system
2. File-based configs (.mcp.json) are documented but create separate configuration system
3. This creates confusion and breaks discoverability/editability expectations

Current Behavior

When using claude mcp add:

claude mcp add task-master-ai npx -y --package=task-master-ai task-master-ai
claude mcp list  # Shows the server

• Server appears in claude mcp list
• No configuration file is created in standard locations:
  • ~/.claude/mcp.json (user-global)
  • .claude/mcp.json (project-local)
  • .mcp.json (project root)

Expected Behavior

CLI-managed MCP servers should be stored in discoverable configuration files following the same pattern as other Claude Code settings:

• Global servers: ~/.claude/mcp.json
• Project servers: .claude/mcp.json or .claude/mcp.local.json

This would align with the existing settings hierarchy:

• ~/.claude/settings.json (user settings)
• .claude/settings.json (project settings)
• .claude/settings.local.json (local project settings)

Benefits of Unified Approach

1. Discoverability: Users can see what MCP servers are configured
2. Editability: Manual editing of configurations when needed
3. Consistency: Same pattern as other Claude Code settings
4. Transparency: No hidden internal storage
5. Version Control: Project-scoped configs can be committed/shared

Environment

• Claude Code CLI version: [current]
• Platform: Linux
• Configuration locations checked:
  • ~/.claude/ (contains settings.json, config.json, but no mcp.json)
  • Project .claude/ directory
  • Project .mcp.json

Related Documentation

The MCP documentation mentions .mcp.json for project-scoped configs, but doesn't clarify the relationship with CLI-managed configs.

[sky0hunter]

Claude Code currently stores these in $HOME/.claude.json I guess.

[gebeer]

Claude Code currently stores these in $HOME/.claude.json I guess.

Thank you. Found it there.

This is still not consistent with other global configs being stored in ~/.claude/

And that .claude.json is a giant blob that contains configs for all projects which doesn't follow the strategy of separation of concerns.

IMO it would be much cleaner to store all project related settings with the project so they can easily be shared across teams also.

[qbedard]

Agreed. This absence is frustrating. I would expect to be able to use ~/.claude/settings.json for this.

[gebeer]

Agreed. This absence is frustrating. I would expect to be able to use ~/.claude/settings.json for this.

Thanks for sharing your experience here. Hope this will help raise attention

[mavam]

I'd like to version control a subset of my ~/.claude directory via git. It's not unusual to have multiple config files in a config directory, but "breaking out" into ~/.claude.json makes it incredibly hard to accomplish configuration locality. Not impossible, but definitely not clean.

So yeah, ~/.claude/mcp.json would solve this an offer a consistent global/project UX.

[LandonSchropp]

I'd also second the idea of an mcp.local.json file. It would be nice to have personal project-specific MCP servers that aren't checked into version control but still retain the benefits of a file-based approach.

[github-actions[bot]]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

[dkbush]

This is still occurring. The CLI behaves differently from the file-based configs, which makes management of the MCP servers very difficult.