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

  1. Create MCP server configuration in ~/.claude/settings.json
  2. Try to use MCP servers with Claude CLI
  3. 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.

View original on GitHub ↗

This issue has 6 comments on GitHub. Read the full discussion on GitHub ↗