The .mcp.json mistakes you cannot see

.mcp.json is a short file, so there should not be much to get wrong.

The expensive mistakes are the ones read as a different, valid setting.

1. A url with no type is read as a stdio server

Leaving out type does not default to http. An entry with no type is read as a stdio server.

A stdio server requires command, so that server is skipped as a configuration error.

{
  "mcpServers": {
    "example": { "url": "https://mcp.example.com/mcp" }
  }
}

MCP server "example" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry

That message exists from v2.1.202. Before it, the same mistake reported command: expected string, received undefined — you wrote a url and were told about a command, which is a long way from the cause.

Under --output-format stream-json it also appears in the system/init event's mcp_server_errors, so a script can detect that the server never loaded.

2. timeout: 500 is not 500 milliseconds

timeout is in milliseconds, and values below 1000 are ignored.

Once ignored it falls through to MCP_TOOL_TIMEOUT, and if that is unset, to its default of about 28 hours.

"timeout": 500      // not 500ms. about 28 hours
"timeout": 600000   // ten minutes

An attempt to shorten it becomes effectively unlimited. Before v2.1.162 values under 1000 were floored to one second instead, so the behaviour changed.

Related, worth knowing:

• timeout is a hard wall-clock limit per tool call, and progress notifications from the server do not extend it
• A timeout of at least 1000 also acts as a floor on the idle timeout — calls are never aborted for idleness sooner than that
• stdio and WebSocket servers have no per-request timer at all

3. Required fields per transport

streamable-http is accepted as an alias so configuration copied from a server's own documentation works unmodified.

ws accepts the same url, headers, headersHelper, timeout and alwaysLoad as http, but claude mcp add --transport does not accept ws — it has to be written as JSON.

4. sse is deprecated

The SSE transport is deprecated. Some services still expose only an SSE endpoint, so it is not always a choice. Where it is, use http.

5. In an untrusted folder, committed approvals are ignored

Servers from .mcp.json need approval, and a repository cannot grant that approval to itself.

enableAllProjectMcpServers and enabledMcpjsonServers committed to the project's .claude/settings.json are ignored in an untrusted folder. The server stays at ⏸ Pending approval, never connected and never health-checked.

A cloned repository cannot approve its own servers.

Three sources of approval still apply in an untrusted folder:

• your own ~/.claude/settings.json
• managed settings
• settings passed with --settings

6. alwaysLoad makes startup wait

With alwaysLoad: true, every tool from that server loads into context at session start regardless of ENABLE_TOOL_SEARCH.

In exchange, startup waits for that server's tool list, since the tools must be present when the first prompt is built. The wait is capped at the 5-second connect timeout.

Use it for a small number of tools Claude needs every turn.

Checking it

The ones visible at write time are mechanically detectable.

npx @quintetkit/ccheck

error .mcp.json:3
      Server "example" has a `url` but no `type`. Add `"type": "http"` (or "sse" / "ws").
      why: https://code.claude.com/docs/en/mcp

warn  .mcp.json:9
      Server "slow": `timeout: 500` is in milliseconds; values below 1000 are ignored.
      why: https://code.claude.com/docs/en/mcp

Every finding cites its source. A rule that cannot be cited is not written.

Everything else that is configured correctly and does nothing — hooks, settings keys, permission rules, subagent files — is collected here.

https://quintetkit.github.io/en/reference/claude-code-silent-config.html

Source

https://code.claude.com/docs/en/mcp

Based on a snapshot taken 2026-09-04.