The Claude Code MCP Configuration Bug That's Wasting Everyone's Time

Published: 12 November 2025 | Development Tools, Claude Code, Technical Issues, Documentation Bugs

TL;DR: The official Claude Code documentation is wrong. If you're trying to configure MCP servers and they're not working, you're probably putting them in the wrong file. Here's what actually works.

The Problem

You've just discovered Model Context Protocol (MCP) servers - those powerful extensions that let Claude Code connect to GitHub, query databases, access your file system, integrate with Jira, or any of the other 200+ tools that transform Claude from a chat interface into an actual development environment.

You read the documentation. You carefully edit ~/.claude/settings.json. You add your MCP configuration. You restart Claude Code.

Nothing happens.

The MCP servers don't load. They don't appear when you run /mcp. You spend the next hour thinking you've misconfigured something, when the truth is much simpler: the documentation is wrong.

The Bug

There's an official bug report (Issue #4976) that exposes the problem:

"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."

Let me be crystal clear: MCP servers configured in ~/.claude/settings.json are completely ignored by Claude Code.

What Actually Works

Stop wasting time. Here are the file locations that actually work:

For User-Level (Global) Configuration

~/.claude.json

Use this when you want MCP servers available across all your projects.

For Project-Level Configuration

.mcp.json

Use this in your project directory when you want project-specific MCP servers.

Example Configuration

Here's what your ~/.claude.json should look like:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/projects"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost/dbname"
      }
    }
  }
}

Not in ~/.claude/settings.json. Not in some nested structure. Just ~/.claude.json.

Why This Matters

This isn't a minor documentation typo. This is a critical configuration error that affects everyone trying to use MCP servers with Claude Code. And MCP servers are one of the most powerful features of Claude Code - they're what transform it from a chat interface into an actual development tool that can:

• Interact with GitHub repositories and manage PRs
• Query databases directly from your conversations
• Access file systems with proper permissions
• Connect to Jira, Slack, Linear, and project management tools
• Fetch real-time data from APIs
• Integrate with hundreds of other development tools

When the documentation sends you to the wrong file, you lose hours troubleshooting a problem that doesn't exist.

The Confusion Gets Worse: Claude Code vs Claude Desktop

Here's what makes this bug even more insidious: Claude Code and Claude Desktop use different configuration files, but the documentation often conflates them.

Claude Desktop (the GUI app) uses:

~/Library/Application Support/Claude/claude_desktop_config.json

Claude Code (the CLI tool) uses:

~/.claude.json

These are completely different tools with completely different config locations. But search for "how to configure MCP in Claude" and you'll find tutorials that mix them up, documentation that assumes you're using one when you're using the other, and Stack Overflow answers that don't specify which tool they're talking about.

Even Claude itself gets confused. Ask Claude (via any interface) "how do I configure an MCP server?" and it might give you Claude Desktop instructions when you're trying to configure Claude Code, or vice versa.

This isn't just a documentation bug - it's a naming and positioning problem. "Claude Code" and "Claude Desktop" are similar enough names that people assume they work the same way. They don't.

Bottom line:

• Using Claude Code (terminal)? → ~/.claude.json
• Using Claude Desktop (GUI app)? → ~/Library/Application Support/Claude/claude_desktop_config.json
• Mixing them up? → Wasted hours debugging

The Documentation Inconsistency

According to Issue #3098, there's a deeper architectural 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 don't clarify the relationship with CLI-managed configs."

This means even the official documentation team doesn't have clarity on where configurations should live, which explains why the docs are wrong.

What You Should Do Right Now

If you've been struggling with MCP configuration:

1. Stop editing ~/.claude/settings.json - It doesn't work for MCP servers
2. Create or edit ~/.claude.json - This is where your MCP servers should live
3. Verify it works:

   claude
   /mcp
   

   You should see your servers listed as "connected"

Alternatively, use the CLI (which writes to ~/.claude.json anyway):

# Example: Add GitHub MCP server
claude mcp add github --scope user npx @modelcontextprotocol/server-github

# Example: Add filesystem MCP server
claude mcp add filesystem --scope user -- npx @modelcontextprotocol/server-filesystem ~/Documents ~/Projects

The Real Cost

How many developer hours have been wasted on this?

• Developers read the docs
• Configure MCPs in the "correct" location
• Spend hours debugging why it doesn't work
• Eventually stumble upon the actual working configuration through trial and error or GitHub issues
• Write frustrated blog posts (hi, that's me)

This is exactly the kind of bug that erodes trust in documentation. When official docs are wrong about fundamental configuration, developers start questioning everything else.

A Message to the Anthropic Team

Fix the documentation. This should be a priority issue. When your docs actively mislead developers about core functionality, you're not just creating a bad experience - you're damaging the adoption of what is genuinely one of the most innovative features in AI-assisted development.

The bug report is from August 2025. It's now November. This needs to be resolved.

For Everyone Else

Share this. Tweet it. Send it to that colleague who was cursing at their terminal yesterday because their MCP servers wouldn't load. Save someone the hours you lost.

And if you're building MCP servers or writing about Claude Code: mention this bug. The more people who know, the less time we collectively waste.

Quick Reference: Which File Do I Need?

What DOESN'T work for Claude Code MCPs:

• ~/.claude/settings.json ❌
• ~/.claude/settings.local.json ❌
• Claude Desktop's config file ❌
• Anywhere the official docs currently tell you ❌

Now go configure your MCP servers properly.

Have you wasted time on this bug? Found other undocumented Claude Code quirks? Drop a comment or reach out - let's document what actually works.

Update Log:

• Initial post: November 2025
• Bug still unresolved as of publication
• Official issue: anthropics/claude-code#4976