[BUG] .mcp.json is not read

[bradleyjames]

Environment

• Platform (select one):
  • [X] Anthropic API
  • [ ] AWS Bedrock
  • [ ] Google Vertex AI
  • [ ] Other:
• Claude CLI version: 1.0.48
• Operating System: macOS 15.5
• Terminal: Terminal App

Bug Description

The MCP documentation refers to configuration in a .mcp.json file (https://docs.anthropic.com/en/docs/claude-code/mcp#environment-variable-expansion-in-mcp-json). I've used MCP config in ~/.claude.json for user level configuration but I can't get Claude Code to read from a .mcp.json file at the user level. I've tried it at ~/.mcp.json, ~/.claude/.mcp.json and ~/.claude/mcp.json. None of these have been picked up by Claude.

My MCP file content is:

{  
  "mcpServers": {
    "gitlab": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${GITLAB_TOKEN}",
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "false",
        "USE_MILESTONE": "false",
        "USE_PIPELINE": "true"
      }
    },
    "atlassian": {
      "type": "sse",
      "url": "https://mcp.atlassian.com/m1/sse"
    }
  }
}

Steps to Reproduce

1. Moved my MCP config from the mcpServers setting ~/.claude.json to one of the .mcp.json paths above.
2. Run claude.
3. Run `/mcp'.

Expected Behavior

Expect my MCP servers to be listed.

Actual Behavior

None of my MCP servers are listed

Additional Context

[elliottkem]

im having the same issue

[piephai]

I can't seem to get it to read from the project level. It seems to just be reading directly from the user level mcp configuration which I added via claude mcp add -s user

[felixzieger]

I think .mcp.json is only for project scoped MCP config.

One thing I stumbled over is that claud mcp list does not list project scoped MCP. You have to run claude and then /mcp to list it.

[je2ryw]

the project scope .mcp.json used to be working, not sure since when it is broken. I am using v1.0.56 right now, and even with /mcp command inside claude code, not working at all.

[ollie-anthropic]

Hey all, thanks a lot for all the feedback here. We'll be trying to make this much clearer and easier to use for you all. Apologies for any issues you're currently facing.

In the meantime, I'll try and help address the comments here one by one:

@bradleyjames - currently, environment variable expansion is only available by .mcp.json (in your project), although I will let you know if this changes promptly for user and local variable expansion. All user and local settings are stored within your ~/.claude.json file. There is no notion of a user-wide .mcp.json file. (It's within ~/.claude.json.)

@felixzieger

One thing I stumbled over is that claude mcp list does not list project scoped MCP. You have to run claude and then /mcp to list it.

Thanks for surfacing this. It feels like a bug. Do you mind mentioning which version of claude code you are on? I can't reproduce this myself. This may be fixed with a later update. Please note that claude mcp list will only list approved MCP servers.

@je2ryw Could you provide more details? For example, could you run /doctor? I can't reproduce this myself.

[felixzieger]

One thing I stumbled over is that claude mcp list does not list project scoped MCP. You have to run claude and then /mcp to list it.

Thanks for surfacing this. It feels like a bug. Do you mind mentioning which version of claude code you are on? I can't reproduce this myself. This may be fixed with a later update. Please note that claude mcp list will only list approved MCP servers.

Ah got it. After I approved the MCP server, it does shows for claude mcp list.

[je2ryw]

claude mcp list No MCP servers configured. Use claude mcp add to add a server.

claude mcp get RepoPrompt RepoPrompt: Scope: Project (shared via .mcp.json)

To remove this server, run: claude mcp remove "RepoPrompt" -s project

/mcp ⎿  No MCP servers configured. Please run /doctor if this is unexpected. Otherwise, run claude mcp or visit https://docs.anthropic.com/en/docs/claude-code/mcp to learn more.

/doctor Claude CLI Diagnostic Currently running: npm-global (1.0.56) Path: /Users/jerry/.nvm/versions/node/v22.15.1/bin/node Invoked: /Users/jerry/.nvm/versions/node/v22.15.1/bin/claude Config install method: global Auto-updates enabled: true Update permissions: Yes

[bradleyjames]

thanks @ollie-anthropic. I would very much appreciate shell expansion in ~/.claude.json as well as breaking out the mcp server configuration from that file. I've lost my configuration because of that file getting corrupted.

[HeroSizy]

Hi @ollie-anthropic, thanks for the clarifications above! I wanted to follow up with a related question about the user scope MCP configuration location.

Currently, as @bradleyjames mentioned, the user-level MCP config is stored together with other settings in ~/.claude.json. In my workflow, I use git to sync my .claude folder across machines, but this approach doesn't capture the MCP server configurations, since they're embedded in a single file rather than a dedicated config file or directory.

Could you share the reasoning behind this design choice? Are there any plans to reconsider and possibly move the user-scope MCP configuration to a separate file or into the ~/.claude/ directory? Separating it out would make it easier to manage, back up, and sync MCP settings independently.

Thanks for your time and for all the improvements!

[qbedard]

Do we have a feature request going for a user-level declarative configuration file like this yet? Or the addition of similar MCP settings to ~/.claude/settings.json?

From what I gather, ~/.claude.json isn’t meant for human editing or declarative configuration. It’s frustrating that we can’t use a file to configure MCP servers unless it’s scoped to a project.

[nkovacic]

I was banging my head why Claude was not reading my .mpc.json file. IT should have been named .mcp.json. I'm adding this comment here for future reference, as a Google search led me to this issue first.

[PaulRBerg]

The title of this issue is a bit misleading since this is not a bug, it's a missing feature.

There is no global MCP JSON file, and that seems to be by design.

But that's a bad design. It would really be helpful to be able to define MCP servers in a bespoke config file.

.claude.json is a big file and my understanding is that it shouldn't be touched by human users.

[sammcj]

Came to log this as a bug as well.

• Claude Code does not parse MCP servers configured in .mcp.json
• Adding MCP servers with claude mcp add --scope project <name> <server> does not work

~/git/someproject $ claude mcp add --scope project aws-core uvx awslabs.core-mcp-server@latest
MCP server aws-core already exists in .mcp.json

~/git/someproject $ claude mcp list
Checking MCP server health...

dev-tools: ~/mcp/mcp-devtools  - ✓ Connected

~/git/someproject $ cat .mcp.json

{
  "mcpServers": {
    "aws-core": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "awslabs.core-mcp-server@latest"
      ],
      "env": {}
    },
    "aws-diagram": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "awslabs.aws-diagram-mcp-server@latest"
      ],
      "env": {}
    }
  }
}

[PaulRBerg]

Related and possible duplicates:

• https://github.com/anthropics/claude-code/issues/6394
• https://github.com/anthropics/claude-code/issues/6839

[blimmer]

I found in https://github.com/anthropics/claude-code/issues/5037 that I needed to call:

claude --mcp-config .mcp.json

for it to pick up the MCP servers. This feels like a regression to me.

It's also annoying that we can't set mcpConfig in .claude/settings.json in the project.

[PaulRBerg]

I wrote this Shell function that restores the previous behavior of Claude Code, i.e., loading MCPs from .mcp.json if an .mcp.json file is present, or otherwise not passing the flag:

# Wrapper for claude CLI that auto-loads .mcp.json if present
function claude() {
    if [[ -f .mcp.json ]]; then
        command claude --mcp-config .mcp.json "$@"
    else
        command claude "$@"
    fi
}

Note: this is needed because otherwise Claude will fail with an error like this if an .mcp.json file doesn't exist:

claude --mcp-config .mcp.json
`);throw Error(`Invalid MCP configuration:
         ^
Error: Invalid MCP configuration:=

[sammcj]

This is tripping up a lot of folks at the companies I work with.

claude mcp add --scope project --transport http context7 https://mcp.context7.com/mcp

Expected behaviour:

1. Claude checks for global MCP servers from ~/.claude.json
2. Claude checks for project MCP servers from .mcp.json
3. Claude loads MCP servers from both global and project config, with project defined MCP servers taking precedence if there is a clash with global

Actual behaviour:

1. Claude loads global MCP servers from ~/.claude.json (why they're configured in a file that contains global state I have no idea!)
2. Claude ignores project MCP servers

---

Even forcing Claude to use .mcp.json does not work:

$ cat .mcp.json
{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@playwright/mcp@latest"
      ],
      "env": {}
    },
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}%

$ claude mcp list --strict-mcp-config .mcp.json
No MCP servers configured. Use `claude mcp add` to add a server.

---

Plenty of people seem to be logging bugs here about this as well:

• https://github.com/anthropics/claude-code/issues/9536
• https://github.com/anthropics/claude-code/issues/5037
• https://github.com/anthropics/claude-code/issues/9536
• https://github.com/anthropics/claude-code/issues/9461

---

I would submit a PR to fix this - but Claude Code is not open source 🤦

[massdo]

Hi, actually I have this behaviour with claude 2.0.24:

-> Project config

claude --strict-mcp-config --mcp-config .mcp.json

-> Global config

claude

-> Merged config

claude --mcp-config .mcp.json

⚠️ Problem

This distinction is quite misleading, because of hidden logic:

-> If a projet config file is present, it is not read at all. -> If a config is specified with --mcp-config, it is not the source of truth, it is a merged config(with global)

Detection should simply follow the context:

-> Project first if local config present, global as fallback -> Config specified with flag --mcp-configmust be source of truth -> Merged config with explicit flag,

Thanks for all your work ! 🙏🙏

[webern]

I feel like the bug is in the design, which involves so many config files in so many places being merged. Please see my review of the experience on #5037 , https://github.com/anthropics/claude-code/issues/5037#issuecomment-3609047115

[boozedog]

hey folks, was able to get this working based on solution here: https://github.com/anthropics/claude-code/issues/9461#issuecomment-3396410009

i added this in <project-folder>/.claude/settings.json (note: not settings.local.json as mentioned in the solution above, as I want to check this into source control)

{
  "enableAllProjectMcpServers": true
}

and then the MCPs listed in <project-folder>/.mcp.json magically appeared in claude code!

tested with both vscode extension as well as in terminal

claude mcp list also showing the MCPs from <project-folder>/.mcp.json

(apologies if I misunderstood this issue)

[PaulRBerg]

Thanks for the tip @boozedog - could that setting (enableAllProjectMcpServers) also be added to the global ~/.claude/settings.json file?

[boozedog]

Thanks for the tip @boozedog - could that setting (enableAllProjectMcpServers) also be added to the global ~/.claude/settings.json file?

i don't know -- didn't try that. i think we can all agree these config files are very very fiddly!

[jimweller]

It seems to work if I don't use --dangerously-skip-permissions because it prompts me to allow the mcp server I have configured in .mcp.json and creates ./.claude/settings.local.json. Once that is created, things work like everybody expects, local mcp is loaded (even with --dangerously-skip-permissions

It seems like you have to have this in ./.claude/settings.local.json

{
  "enabledMcpjsonServers": [
    "atl"
  ],
  "enableAllProjectMcpServers": true
}

This is what I see without skipping permissions

❯ claude
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                                                                                                                                                                                                                          │
│ New MCP server found in .mcp.json: atl                                                                                                                                                                                                   │
│                                                                                                                                                                                                                                          │
│ MCP servers may execute code or access system resources. All tool calls require approval. Learn more in the MCP documentation.                                                                                                           │
│                                                                                                                                                                                                                                          │
│ ❯ 1. Use this and all future MCP servers in this project                                                                                                                                                                                 │
│   2. Use this MCP server                                                                                                                                                                                                                 │
│   3. Continue without using this MCP server                                                                                                                                                                                              │
│                                                                                                                                                                                                                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
   Enter to confirm · Esc to reject

[jimweller]

It seems like you have to have this in ./.claude/settings.local.json

{
  "enableAllProjectMcpServers": true
}

[XhstormR]

Would appreciate the ability to provide a user-level MCP configuration file, such as .claude/mcp.json.