`.mcp.json` Under `.claude/` Never Loads

The annoyance

I put .mcp.json next to CLAUDE.md under .claude/ because that is where the other Claude files live, and so it looks correct, and /mcp still shows nothing.

I had the usual suspects, a stale CLI and a server that failed to start and a key I had misspelled, and then I moved the same file to the repository root and the servers appeared, and so the copy under .claude/ had never been read.

The trap is easy because three names sit next to each other and I treat them as one place: project .mcp.json, user ~/.claude.json, and the .claude/ folder. They are not the same file, and Claude Code does not look in the folder for this one.

What Anthropic actually says

From the official Debug your configuration page, common-causes table:

Symptom: “MCP servers in `.mcp.json` never load”
Cause: “File is under `.claude/`, or its servers sit under a top-level `servers` key, as in VS Code's `mcp.json`, instead of `mcpServers`”
Fix: “Project MCP config goes at the repository root as `.mcp.json`, not inside `.claude/`, with servers under the `mcpServers` key.”

The next row is the same miss in a different file:

Symptom: “MCP servers added under `mcpServers` in `settings.json` never appear”
Cause: “`settings.json` does not read an `mcpServers` key”
Fix: “Define project servers in `.mcp.json` at the repository root, or run `claude mcp add --scope user` for user-scoped servers.”

The MCP page is the same rule. Project scope is stored at the project root, under the mcpServers key:

“Project-scoped servers enable team collaboration by storing configurations in a `.mcp.json` file at your project's root directory. When you add a project-scoped server, Claude Code automatically creates or updates this file with the appropriate configuration structure. Check `.mcp.json` into version control so everyone on your team gets the same MCP tools and services.”

The right place

The file Claude Code reads for the project is .mcp.json at the repository root, and the servers sit under mcpServers. This is the official shape, cut down to one HTTP server:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

These three shapes look finished and never load. The first is the same object under .claude/.mcp.json:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

The second is the VS Code key. Claude Code does not read a top-level servers object:

{
  "servers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

The third is mcpServers inside settings.json. That file does not read the key, so user-scoped servers go in ~/.claude.json through claude mcp add --scope user, and project servers stay in root .mcp.json:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Two more traps that look like the same failure

A project-scoped server can be in the right file and still stay off. Official debug text:

“Project-scoped servers in `.mcp.json` require a one-time approval. If the prompt was dismissed, the server stays disabled until you approve it from `/mcp`.”

If I dismissed that prompt, I run /mcp and approve the server once, and so the file was never the problem.

A server can also fail to start because a relative command or args path is resolved against the directory I launched Claude Code from, not against the location of .mcp.json:

“A server that fails to start shows as failed in `/mcp`. Relative file paths in `command` or `args` are a frequent cause, since they resolve against the directory you launched Claude Code from rather than the location of `.mcp.json`.”
Fix: “Use absolute paths for local scripts. Executables on your `PATH` like `npx` or `uvx` work as-is.”

Use an absolute path for a local script. Leave npx and uvx as they are, because those resolve on PATH.

Prove it loaded

From the terminal, list what Claude Code can see:

claude mcp list

Then open a session and run /mcp. I should see the server, its connection status, and whether it still needs approval. If it shows as connected and lists zero tools, official debug text is to reconnect:

“A server that shows as connected but lists zero tools has started successfully but isn't returning a tool list. Select Reconnect from `/mcp`.”

If the server is missing from both lists, the file is still in the wrong place or the key is still the wrong one.

Checklist

1. Put .mcp.json at the repository root, not under .claude/.
2. Put servers under mcpServers, not under a top-level servers key.
3. Take any mcpServers block out of settings.json.
4. Approve the project server in /mcp if I dismissed the prompt.
5. Use absolute paths for local command and args, and leave npx and uvx as they are.
6. Run claude mcp list, then /mcp, and reconnect if the tool count is zero.

Why it fails

I treat .mcp.json under .claude/ as the project MCP file because that is where the other Claude files live. For CLAUDE.md that is true. For MCP it is not. Same family as permissions in ~/.claude.json — the file looks correct, the name is the one I already edit, and the documented place is a different one. Claude Code ignores AGENTS.md is the other filename miss: the file sits in the tree and never loads. Auto in project settings is the same class of miss: valid JSON, and the documented file is a different one.

If you want to run this with other operators rather than on your own, we are doing that in the public Skool community, and that is https://www.skool.com/navaigate.

Sources

• Anthropic — Debug your configuration
• Anthropic — Connect Claude Code to tools via MCP
• Permissions in ~/.claude.json Are Ignored
• Claude Code Ignores AGENTS.md
• Auto in Project Settings Does Nothing
• NavAIgate Skool community