Quartet / Quintet

2026-09-10  ·  mcp · claudecode · 設定 · 個人開発 · devops

timeout に 500 と書いたら、28時間になった

たまに固まる MCP サーバがあったので、短い綱を付けました。

{ "mcpServers": { "flaky": { "type": "http", "url": "...", "timeout": 500 } } }

timeout はミリ秒なので、これで0.5秒のつもりです。

1000 未満の値は無視されます。 呼び出しは MCP_TOOL_TIMEOUT に落ち、それも設定されていなければ、 その既定である約28時間になります。

いちばんきつい制限を書いて、いちばん緩いものを作っていました。

v2.1.162 より前は、1000 未満は1秒に丸められていました。 私の頭にあったのはその挙動です。 仕様が変わり、私の設定は変わらなかった。

節を通しで読んで、関連することが3つ分かりました。

type の無い url は、stdio サーバとして読まれる

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

http が既定になるわけではありません。 type の無いエントリは stdio サーバで、stdio には command が要るので、 そのサーバは設定エラーとして飛ばされます。

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 にも出ます。 機械で検知できる経路は、いまのところこれだけでした。

クローンしたリポジトリは、自分のサーバを自分で承認できない

これがいちばん時間を使いました。権限まわりのバグに見えるからです。

.mcp.json のサーバは承認が要ります。 enableAllProjectMcpServers や enabledMcpjsonServers を プロジェクトの .claude/settings.json に commit することはできて、 untrusted なフォルダでは無視されます。 サーバは ⏸ Pending approval のまま、接続もヘルスチェックもされません。

言われてみれば正しい。 リポジトリが自分の MCP サーバを自分で承認できるなら、 クローンした人の環境でコードを走らせる経路になります。

untrusted なフォルダでも効く承認元は3つです。 自分の ~/.claude/settings.json、管理設定、--settings で渡した設定。

全部に共通していること

どれも、読み込まれる設定です。 エラーも出ず、気づく形の警告も出ず、 ファイルに書いてあるのと違うことをしている系が動き続けます。

timeout: 500 がいちばん鋭い例です。 ファイルは0.5秒と言い、システムは丸一日と言い、 どちらも設計どおりに動いています。

これらを踏んだあとで設定の検査ツールに求めるのは、規則の数ではありません。 持っている規則が、正しいものに対して絶対に鳴らないことです。

そもそも私が起動時の出力を読まなくなったのは、 そこに一度も重要なものが出たことがなかったからで、 実際に出たときには、もう読まない癖がついていました。

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.

トランスポート別の必須項目を含めた全一覧はこちらです。

https://quintetkit.github.io/reference/claude-code-mcp-json.html

Claude Code に設計・実装・レビューを別々の人格として分担させ、GitHub Issue と ブランチを軸に並列開発を回すための設定一式を MIT で公開しています。 コピーして ./setup.sh を叩けば動きます。技術スタックには依存しません。

https://github.com/quintetkit/quartet

このワークフローだけで実際にツールを 1 つ作りました。Issue の分割から PR、 レビュー、マージまで記録が全部残っています。うまくいかなかった箇所も消していません。

https://github.com/quintetkit/mdlinkcheck

UI 設計人格・レビュー基準・Issue 単位の並列実行スクリプト・実践ガイド 11 章を 足したものは製品ページにあります。

実践ガイド全 11 章は Zenn Book で読めます（¥1,500・2章まで無料）。

https://zenn.dev/quintetkit/books/claude-code-parallel-workflow

設定一式（5人格・スクリプト・ガイド全文）の配布はこちらです。

https://quartet-dev.booth.pm/items/8807156

この運用そのものを配っています

4 人格版 Quartet は MIT で無料公開しています。UI 設計人格・レビュー基準・ Issue 単位の並列実行スクリプト・実践ガイド 11 章を足した Quintet は有料版です。

無料版を見る 製品ページ