Documentation incorrect about MCP configuration file location
Resolved 💬 6 comments Opened Aug 2, 2025 by mjochum64 Closed Aug 15, 2025
Environment
- Platform (select one):
- [x] Anthropic API
- Claude CLI version: 1.0.67 (Claude Code)
- Operating System: Linux 6.15.8-arch1-2 (EndeavourOS)
- Terminal: Ptyxis
Bug Description
The Claude CLI documentation incorrectly states that MCP server configuration should be placed in ~/.claude/settings.json. This configuration file location does not work for MCP servers.
Steps to Reproduce
- Create MCP server configuration in ~/.claude/settings.json
- Try to use MCP servers with Claude CLI
- MCP servers are not recognized/loaded
Expected Behavior
MCP servers should be loaded and available when configured in ~/.claude/settings.json as documented.
Actual Behavior
MCP servers are only recognized when configured in:
- Local .mcp.json file in the project directory, OR
- .claude.json file in the HOME directory (~/.claude.json)
The ~/.claude/settings.json configuration is ignored for MCP servers.
Additional Context
This appears to be a documentation issue where the correct MCP configuration file locations are not properly documented. The actual working configuration files differ from what's stated in the documentation.
This issue has 6 comments on GitHub. Read the full discussion on GitHub ↗