### Preflight Checklist - [x] I have searched [existing issues](https://github.com/anthropics/claude-code/issues?q=is%3Aissue%20state%3Aopen%20label%3Abug) and this hasn't been reported yet - [x] This is a single bug report (please file separate reports for different bugs) - [x] I am using the latest version of Claude Code ### What's Wrong? MCP servers configured in `~/.claude/mcp.json` or via a `mcpServers` key in `~/.claude/settings.json` are completely absent from `/mcp` — not shown as err

[BUG] MCP servers silently absent from /mcp when configured via mcp.json or settings.json — wrong config store

Resolved 💬 3 comments Opened Mar 21, 2026 by yuty2z63 Closed Mar 21, 2026

Preflight Checklist

[x] I have searched existing issues and this hasn't been reported yet
[x] This is a single bug report (please file separate reports for different bugs)
[x] I am using the latest version of Claude Code

What's Wrong?

MCP servers configured in ~/.claude/mcp.json or via a mcpServers key in ~/.claude/settings.json are completely absent from /mcp — not shown as errored, not shown as needing authentication, simply not present. There is no error message, no warning, and no indication that the config files are being ignored.

The silent failure makes this extremely difficult to diagnose. "Server absent" looks identical whether you've edited the wrong file, have a broken binary, or are missing an env var — so there's nothing to point you toward the real cause.

What Should Happen?

One of:

Claude Code should read ~/.claude/mcp.json for MCP server config (it's named mcp.json — this is the obvious place to put it), or
Claude Code should warn or error when ~/.claude/mcp.json or a mcpServers key in settings.json is detected but will be ignored, and
When a server fails to spawn, it should appear in /mcp with an error state rather than being silently omitted

Error Messages/Logs

None — this is the problem. There are no error messages at any point. The server is simply absent from `/mcp` with no indication of why.

Steps to Reproduce

Add an MCP server entry to ~/.claude/mcp.json:

``json { "mcpServers": { "myserver": { "type": "stdio", "command": "node", "args": ["/path/to/index.js"], "env": { "MY_VAR": "value" } } } }``

Open (or restart) Claude Code in any project directory

Run /mcp

Server is absent — no error, no warning

Alternatively:

Add a mcpServers key to ~/.claude/settings.json with the same structure
Same result — server absent, no error

The fix (for others finding this): use claude mcp add instead of editing JSON files manually — this writes to ~/.claude.json, which is the actual config store Claude Code reads at runtime. Neither ~/.claude/mcp.json nor ~/.claude/settings.json are read for MCP config.

claude mcp add myserver -e MY_VAR=value -- /usr/bin/node /path/to/index.js
claude mcp list  # verify registration

Second silent failure mode: even when registered correctly via claude mcp add, using a bare command name (node) instead of an absolute path (/usr/bin/node) causes the same silent failure. Claude Code spawns MCP servers with a restricted PATH — bare names may not resolve. Always use absolute paths.

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.1.81

Platform

Other

Operating System

Ubuntu/Debian Linux

Terminal/Shell

Other

Additional Information

<html>
<body>
<!DOCTYPE html><p cid="n213" mdtype="paragraph" class="md-end-block md-p md-focus" style="box-sizing: border-box; line-height: inherit; orphans: 4; margin: 0.8em 0px; white-space: pre-wrap; position: relative; color: rgb(51, 51, 51); font-family: "Open Sans", "Clear Sans", "Helvetica Neue", Helvetica, Arial, "Segoe UI Emoji", "SF Pro", sans-serif; font-size: 16px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;">The core issue is that three files exist which appear to be legitimate MCP config locations, but only one is actually read:<figure class="md-table-fig table-figure" cid="n214" mdtype="table" style="box-sizing: border-box; margin: 1.2em 0px; overflow-x: auto; max-width: calc(100% + 16px); padding: 0px; cursor: default; color: rgb(51, 51, 51); font-family: "Open Sans", "Clear Sans", "Helvetica Neue", Helvetica, Arial, "Segoe UI Emoji", "SF Pro", sans-serif; font-size: 16px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;">
File | What it actually does
-- | --
~/.claude/settings.json | User preferences (theme, model, permissions, hooks) — not MCP
~/.claude/mcp.json | Not read by Claude Code at runtime — appears to be a legacy or docs artefact
~/.claude.json | Actual MCP config store — written by claude mcp add, read by the runtime

</figure><p cid="n227" mdtype="paragraph" class="md-end-block md-p" style="box-sizing: border-box; line-height: inherit; orphans: 4; margin: 0.8em 0px; white-space: pre-wrap; position: relative; color: rgb(51, 51, 51); font-family: "Open Sans", "Clear Sans", "Helvetica Neue", Helvetica, Arial, "Segoe UI Emoji", "SF Pro", sans-serif; font-size: 16px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;">The name <code style="box-sizing: border-box; font-family: var(--monospace); text-align: left; vertical-align: initial; border: 1px solid rgb(231, 234, 237); background-color: rgb(243, 244, 244); border-radius: 3px; padding: 0px 2px; font-size: 0.9em;">mcp.json</code> makes it the obvious first choice. The <code style="box-sizing: border-box; font-family: var(--monospace); text-align: left; vertical-align: initial; border: 1px solid rgb(231, 234, 237); background-color: rgb(243, 244, 244); border-radius: 3px; padding: 0px 2px; font-size: 0.9em;">settings.json</code> file has a JSON structure that looks like it accepts MCP config. Neither work. Both fail without any indication they're being ignored.<p cid="n228" mdtype="paragraph" class="md-end-block md-p" style="box-sizing: border-box; line-height: inherit; orphans: 4; margin: 0.8em 0px; white-space: pre-wrap; position: relative; color: rgb(51, 51, 51); font-family: "Open Sans", "Clear Sans", "Helvetica Neue", Helvetica, Arial, "Segoe UI Emoji", "SF Pro", sans-serif; font-size: 16px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;">This cost two days of debugging and significant API usage attempting to diagnose what appeared to be a server or network issue, when the cause was purely a config file routing problem.<p cid="n229" mdtype="paragraph" class="md-end-block md-p" style="box-sizing: border-box; line-height: inherit; orphans: 4; margin: 0.8em 0px; white-space: pre-wrap; position: relative; color: rgb(51, 51, 51); font-family: "Open Sans", "Clear Sans", "Helvetica Neue", Helvetica, Arial, "Segoe UI Emoji", "SF Pro", sans-serif; font-size: 16px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;">Suggested fixes (in priority order):<ol class="ol-list" start="" cid="n230" mdtype="list" style="box-sizing: border-box; margin: 0.8em 0px 0px; padding-left: 30px; position: relative; color: rgb(51, 51, 51); font-family: "Open Sans", "Clear Sans", "Helvetica Neue", Helvetica, Arial, "Segoe UI Emoji", "SF Pro", sans-serif; font-size: 16px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;"><li class="md-list-item" cid="n231" mdtype="list_item" style="box-sizing: border-box; margin: 0px; position: relative;">Read <code style="box-sizing: border-box; font-family: var(--monospace); text-align: left; vertical-align: initial; border: 1px solid rgb(231, 234, 237); background-color: rgb(243, 244, 244); border-radius: 3px; padding: 0px 2px; font-size: 0.9em;">~/.claude/mcp.json</code> as documented/implied by the filename</li><li class="md-list-item" cid="n233" mdtype="list_item" style="box-sizing: border-box; margin: 0px; position: relative;">Emit a warning when <code style="box-sizing: border-box; font-family: var(--monospace); text-align: left; vertical-align: initial; border: 1px solid rgb(231, 234, 237); background-color: rgb(243, 244, 244); border-radius: 3px; padding: 0px 2px; font-size: 0.9em;">mcp.json</code> or <code style="box-sizing: border-box; font-family: var(--monospace); text-align: left; vertical-align: initial; border: 1px solid rgb(231, 234, 237); background-color: rgb(243, 244, 244); border-radius: 3px; padding: 0px 2px; font-size: 0.9em;">mcpServers</code> in <code style="box-sizing: border-box; font-family: var(--monospace); text-align: left; vertical-align: initial; border: 1px solid rgb(231, 234, 237); background-color: rgb(243, 244, 244); border-radius: 3px; padding: 0px 2px; font-size: 0.9em;">settings.json</code> is detected but ignored</li><li class="md-list-item" cid="n235" mdtype="list_item" style="box-sizing: border-box; margin: 0px; position: relative;">Show a "failed to spawn" error state in <code style="box-sizing: border-box; font-family: var(--monospace); text-align: left; vertical-align: initial; border: 1px solid rgb(231, 234, 237); background-color: rgb(243, 244, 244); border-radius: 3px; padding: 0px 2px; font-size: 0.9em;">/mcp</code> instead of omitting the server silently</li><li class="md-list-item md-focus-container" cid="n237" mdtype="list_item" style="box-sizing: border-box; margin: 0px; position: relative;">Clarify in docs that <code style="box-sizing: border-box; font-family: var(--monospace); text-align: left; vertical-align: initial; border: 1px solid rgb(231, 234, 237); background-color: rgb(243, 244, 244); border-radius: 3px; padding: 0px 2px; font-size: 0.9em;">~/.claude.json</code> (not <code style="box-sizing: border-box; font-family: var(--monospace); text-align: left; vertical-align: initial; border: 1px solid rgb(231, 234, 237); background-color: rgb(243, 244, 244); border-radius: 3px; padding: 0px 2px; font-size: 0.9em;">mcp.json</code>) is the operational config store and that <code style="box-sizing: border-box; font-family: var(--monospace); text-align: left; vertical-align: initial; border: 1px solid rgb(231, 234, 237); background-color: rgb(243, 244, 244); border-radius: 3px; padding: 0px 2px; font-size: 0.9em;">claude mcp add</code> is the only supported write path</li></ol>
</body>
</html>

View original on GitHub ↗

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