I had an MCP server that occasionally hung, so I gave it a short leash:
{ "mcpServers": { "flaky": { "type": "http", "url": "...", "timeout": 500 } } }
timeout is in milliseconds, so that reads as half a second.
Values below 1000 are ignored. The call falls through to
MCP_TOOL_TIMEOUT, and if that is unset, to its default — about 28 hours.
I had written the tightest limit I could and produced the loosest one available.
Before v2.1.162 a value under 1000 was floored to one second, which is the
behaviour I had in my head. It changed, and nothing in my configuration changed with it.
Three related things I only learned by reading the whole section:
timeout is a url with no type is read as a stdio server
{ "mcpServers": { "example": { "url": "https://mcp.example.com/mcp" } } }
There is no defaulting to http. An entry with no type is a stdio server,
stdio requires command, and so the server is skipped as a configuration error:
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 a server never loaded. That is
the only machine-readable path I have found for it.
This one cost me the most time, because it looks like a permissions bug.
Servers from .mcp.json need approval. You can commit
enableAllProjectMcpServers or enabledMcpjsonServers to the project's
.claude/settings.json — and in an untrusted folder they are ignored. The
server sits at ⏸ Pending approval, never connected, never health-checked.
Which is correct, and obvious once stated: a repository that could approve its own MCP servers would be a way to run code on anyone who clones it.
Three sources of approval still apply in an untrusted folder: your own
~/.claude/settings.json, managed settings, and settings passed with
--settings.
Every one of them is a configuration that loads. No error, no warning you
would notice, and a running system that is doing something other than what the
file says.
timeout: 500 is the sharpest example: the file says half a second, the system
says a day and change, and both are working as designed.
What I want from a configuration checker, having been on the wrong end of these,
is not more rules. It is that the ones it does have never fire on something
correct — because the reason I stopped reading startup output in the first place
was that nothing there had ever mattered, and by the time something did, I had
already trained myself past it.
npx @quintetkit/ccheck
error .mcp.json:3
Server "example" has a `url` but no `type`. Add `"type": "http"` (or "sse" / "ws").
warn .mcp.json:9
Server "flaky": `timeout: 500` is in milliseconds; values below 1000 are ignored.
The full set, including the required field per transport:
https://quintetkit.github.io/en/reference/claude-code-mcp-json.html
I publish the configuration for splitting Claude Code into separate personas —
Architect, Coder, Reviewer, Conflict Resolver — under MIT. Copy it, run
./setup.sh, and it works. It does not depend on your tech stack.
https://github.com/quintetkit/quartet
I built one real tool using nothing but this workflow. Every Issue, PR, review
and merge is still there. The parts that went wrong were not deleted.
https://github.com/quintetkit/mdlinkcheck
The version that adds a UI Designer persona, review criteria, a per-Issue
parallel execution script and a 11-chapter guide is on the
The full kit — five personas, the scripts and the complete guide — is available here.