MCP Configuration Inconsistency: CLI-managed vs File-based configs
Status Closed — not planned
Maintainer reply None cached
Activity 10 comments · opened Jul 7, 2025 · closed Jan 11, 2026
Problem
There's an architectural inconsistency in how MCP server configurations are managed in Claude Code:
- CLI-managed configs (
claude mcp add) are stored internally and not visible in file system - File-based configs (
.mcp.json) are documented but create separate configuration system - 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.jsonor.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
- Discoverability: Users can see what MCP servers are configured
- Editability: Manual editing of configurations when needed
- Consistency: Same pattern as other Claude Code settings
- Transparency: No hidden internal storage
- 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.
10 Comments
Claude Code currently stores these in
$HOME/.claude.jsonI guess.Thank you. Found it there.
This is still not consistent with other global configs being stored in
~/.claude/And that
.claude.jsonis 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.
Agreed. This absence is frustrating. I would expect to be able to use
~/.claude/settings.jsonfor this.Thanks for sharing your experience here. Hope this will help raise attention
I'd like to version control a subset of my
~/.claudedirectory via git. It's not unusual to have multiple config files in a config directory, but "breaking out" into~/.claude.jsonmakes it incredibly hard to accomplish configuration locality. Not impossible, but definitely not clean.So yeah,
~/.claude/mcp.jsonwould solve this an offer a consistent global/project UX.I'd also second the idea of an
mcp.local.jsonfile. 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.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.
This is still occurring. The CLI behaves differently from the file-based configs, which makes management of the MCP servers very difficult.
This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.
This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.