.mcp.json で書き間違えても気づけないところ
.mcp.json は短いファイルなので、間違いは少ないはずです。
実際にいちばん高くつくのは、間違いが「別の正しい設定」として読まれるときです。
1. url だけ書くと、stdio サーバとして読まれる
type を書き忘れた場合、既定として http になるわけではありません。
type の無いエントリは stdio サーバとして読まれます。
stdio サーバには command が必要なので、そのサーバは設定エラーとして飛ばされます。
{
"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
この文言が出るのは v2.1.202 以降です。それより前は
command: expected string, received undefined と出ていました。
url を書いたのに command の話をされるので、原因に辿り着きにくい形でした。
--output-format stream-json で走らせている場合は、
system/init イベントの mcp_server_errors にも出ます。スクリプトから検知できます。
2. timeout: 500 は 500ミリ秒になりません
timeout はミリ秒です。そして1000 未満の値は無視されます。
無視されたあとは MCP_TOOL_TIMEOUT に落ち、それも設定されていなければ
その既定である約28時間になります。
"timeout": 500 // → 500ms ではない。約28時間
"timeout": 600000 // → 10分
短くしたつもりが、事実上の無制限になります。
v2.1.162 より前は 1000 未満は1秒に丸められていたので、挙動が変わっています。
関連して知っておくとよいこと。
timeoutは1回のツール呼び出しに対する実時間の上限で、 サーバからの進捗通知では延びません- 1000 以上の
timeoutは、アイドル打ち切りの下限にもなります。 その時間より早くアイドルで打ち切られることはありません - stdio と WebSocket のサーバにはリクエスト単位のタイマーがありません
3. トランスポート別の必須項目
type |
必須 |
|---|---|
| （無し） | command — type を省くと stdio 扱い |
stdio |
command |
http |
url |
streamable-http |
url — http の別名。MCP 仕様側の呼び方 |
sse |
url |
ws |
url |
streamable-http が別名として受け付けられるので、
サーバのドキュメントからそのまま貼っても動きます。
ws は url / headers / headersHelper / timeout / alwaysLoad を
http と同じように受け付けますが、claude mcp add --transport は ws を受け付けません。
JSON で書く必要があります。
4. sse は非推奨
SSE トランスポートは非推奨です。 ただし SSE しか出していないサービスもあるので、
選べない場合はあります。選べるなら http にしてください。
5. untrusted なフォルダでは、承認の設定が無視される
.mcp.json のサーバは承認が要ります。
そしてその承認をリポジトリ側から与えることはできません。
enableAllProjectMcpServers や enabledMcpjsonServers を
プロジェクトの .claude/settings.json にコミットしても、
untrusted なフォルダでは無視されます。 サーバは ⏸ Pending approval のまま、
接続もヘルスチェックもされません。
クローンしてきたリポジトリは、自分のサーバを自分で承認できません。
untrusted なフォルダでも効く承認元は3つです。
- あなた自身の
~/.claude/settings.json - 管理設定
--settingsで渡した設定
6. alwaysLoad は起動を待たせる
alwaysLoad: true にすると、そのサーバのツールは
ENABLE_TOOL_SEARCH の設定に関係なく、セッション開始時に全部読み込まれます。
引き換えに、起動がそのサーバのツール一覧を待ちます （最初のプロンプトを組む時点で揃っている必要があるため）。 待ち時間は接続タイムアウトの5秒が上限です。
毎ターン必要な少数のツールにだけ使ってください。
検査する
上のうち、書いた時点で分かるものは機械で見つけられます。
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
指摘には必ず出典が付きます。 根拠を示せないものはルールにしていません。
「正しく書けているのに何も起きない」場所を、hook・設定キー・権限ルール・ サブエージェントまで含めて1枚にまとめたものはこちらです。
https://quintetkit.github.io/reference/claude-code-silent-config.html
出典
https://code.claude.com/docs/en/mcp
2026-09-04 に取得したスナップショットを元にしています。