Documentation incorrect about MCP configuration file location

[mjochum64]

Environment

• Platform (select one):
  • 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.

[coygeek]

Github Issue Response

The user who submitted the GitHub issue is correct about their experience and observation, but their conclusion that the documentation is incorrect is based on a misunderstanding.

The documentation is technically accurate, but it is confusing on this specific point, which is what led to the user's problem.

Here is the detailed explanation:

1. Why the User's Experience is Correct

The user tried to define an MCP server inside ~/.claude/settings.json, and it failed. They are 100% correct; that is not where MCP server definitions go.

They also correctly discovered that project-level definitions go in .mcp.json and that a user-level configuration in ~/.claude.json works. The CHANGELOG (v1.0.7) confirms that .claude.json was a legacy settings file, and it's plausible that user-level MCP server definitions were never migrated out of it to maintain backward compatibility.

So, their troubleshooting and findings are accurate.

2. Why the Documentation is Technically Accurate

The user's claim is: "The Claude CLI documentation incorrectly states that MCP server configuration should be placed in ~/.claude/settings.json."

This claim is false. The documentation never says this.

Here is what the documentation actually says:

• To configure MCP servers, use the claude mcp command. The en/docs/claude-code/mcp page is very clear. It instructs users to run claude mcp add .... It never tells the user to manually edit a JSON file for this purpose.
• Project-level servers go in .mcp.json. The documentation explicitly states that when you use claude mcp add -s project ..., it creates a .mcp.json file. This matches the user's findings.
• settings.json is for managing permissions of MCP servers, not defining them. The en/docs/claude-code/settings page lists keys like enabledMcpjsonServers and clearly describes them as applying to servers "defined in project .mcp.json files."

The documentation correctly guides the user to use the command-line tool, which handles the file placement automatically. It never instructs them to place a server definition in settings.json.

3. The Source of the Confusion (Why the User Got It Wrong)

This is the most critical part. Even though the documentation is technically right, it's easy to see how the user got confused.

1. Logical Assumption: A developer sees a new, centralized settings.json file. It's a very reasonable (but incorrect) assumption that all settings, including MCP server definitions, would go there.
2. Lack of an Explicit Warning: The documentation for settings.json does not have a clear "What does NOT go in this file" section. It doesn't explicitly say, "Warning: Do not place MCP server definitions here; use the claude mcp command instead." This is an error of omission that creates a trap for users.
3. Multiple Config Files: The system uses .claude/settings.json, .claude/settings.local.json, .claude/agents/, .claude/commands/, CLAUDE.md, .mcp.json, and the legacy ~/.claude.json. This is a complex configuration surface, and the documentation doesn't provide a single, clear overview of which file does what.

Final Verdict

• Is the user correct? Yes, about the behavior of the software.
• Does the documentation need to change? Yes. While not technically "wrong," it is unclear and led a user to a predictable point of failure.

How Anthropic could improve the documentation:

The documentation team should add a clear note in the en/docs/claude-code/settings page that explicitly states that MCP server definitions are managed separately via the claude mcp command and are not to be placed in settings.json. This would prevent the exact confusion this user experienced.

[J4k3j4k3]

Thanks @mjochum64! Great writeup!

For other also struggling with "failed to connect" MCP issues everywhere like me, using absolute paths fixed it. For example:

claude mcp add yfinance -- "C:\nvm4w\nodejs\node.exe" "C:\nvm4w\nodejs\node_modules@szemeng76\yfinance-mcp-server\build\index.js"

[rahulrajaram]

@mjochum64 , thanks so much. I can't believe this has not been stated clearly in documentation. I think most people want the global ~/.claude.json approach. You must have the "mcpServers" JSON key at the top-level:

(3124) ➜ head -n20 ~/.claude.json
{
  "numStartups": ...,
  "installMethod": "unknown",
  "autoUpdates": true,
  "editorMode": "vim",
  ...
  "mcpServers": {
      ...
  }

and yes, to @J4k3j4k3 's point, you will have deterministic behaviour with absolute paths.

[github-actions]

Found 3 possible duplicate issues:

1. [BUG] .mcp.json is not read #3321
2. Documentation error: settings.json location #1202
3. Wrong Documentation for Config settings. #3556

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[github-actions]

This issue has been automatically closed as a duplicate of #3321.

If this is incorrect, please re-open this issue or create a new one.

🤖 Generated with Claude Code