つなぎ方 ― stdio と Streamable HTTP

stdio：子プロセスとして起動して、パイプで話す

手元で動かすサーバーは、ほぼこれです。クライアントがコマンドを実行してサーバーを起動し、そのプロセスの標準入出力を掴みます。

- クライアントは、サーバーの stdin にリクエストと通知を書く
- サーバーは、stdout に応答と通知を書く
- メッセージは改行で区切る。1行1メッセージ
- したがってメッセージの中に改行を含めてはならない

ネットワークを通らないので速く、認証も要りません。資格情報は環境変数など、ローカルの手段で渡します。

終わらせ方も決まっています。クライアントは入力ストリームを閉じ、サーバーが終わるのを待ちます。サーバー側は標準入力が閉じたら速やかに終了するのが行儀です。終わらなければ強制終了されます。

stdout に、MCPメッセージ以外を書いてはいけない

ここが stdio でいちばん多い事故です。仕様にはこう書かれています。

サーバーは、有効なMCPメッセージ以外のものを `stdout` に書いてはならない（MUST NOT）。

つまり console.log("ここまで来た") や print(result) を1行入れただけで、その行がJSON-RPCとして解釈され、パースに失敗し、接続が壊れます。処理は正しいのに動かないという、いちばん時間を溶かす壊れ方です。

ログを出したいときは stderr を使います。こちらは自由に書いてよく、クライアントは受け取っても無視しても構いません。`stderr` に出力があること自体はエラーの印ではない、とも明記されています。

NG: console.log("debug")      → stdout が汚れて接続が壊れる
OK: console.error("debug")    → stderr なので安全

なお、2026-07-28 版ではプロトコル経由のログ送信（logging）は非推奨になりました。新しく作るなら stderr か OpenTelemetry を使います。

Streamable HTTP：1つの口に POST して、流れて返る

遠くのサーバーはこちらです。クライアントは単一のエンドポイントに HTTP POST でメッセージを送ります。返事は2通りあります。

- 1つのJSONオブジェクトとして即返る
- そのリクエスト専用の SSE（Server-Sent Events） ストリームとして流れてくる

長い処理の途中経過を送りたいときに、後者が効きます。

HTTPなので、認証は普通のHTTPのやり方が使えます。Authorization: Bearer … を付けるのが基本形で、仕様は OAuth でトークンを取ることを推奨しています。詳しくは第5章で扱います。

このトランスポートでは、_meta の内容が HTTPヘッダにも写されます。間に立つプロキシなどが、本文をパースしなくても振り分けられるようにするためです。ただし本文が正で、食い違ったときにどう拒否するかはトランスポート側が決めます。

途中でやめたいときは、stdio では notifications/cancelled を送り、HTTPではそのリクエストのストリームを閉じます。

どちらを選ぶか

迷ったときの目安です。

触る対象が利用者の手元にあるなら stdio。 ファイル、Git リポジトリ、ローカルのデータベース。ネットワーク越しにやる意味がありません。

皆で同じものを見るなら Streamable HTTP。 社内検索、課題管理、顧客データ。1か所で権限を管理できます。

両方を出しているサービスもあります。同じデータ層なので、実装を共有して口だけ2つ用意できるからです。

版は毎回のリクエストが運ぶ

状態を持たないので、「この接続は何版か」という覚え方はしません。リクエストごとに `_meta` が版を運びます。

サーバーが対応していない版で来たら、対応している版を並べたエラーを返し、クライアントが選び直します。

古いサーバーと繋ぐときは、まず server/discover を投げるのが推奨です。

- DiscoverResult が返る → 新しい世代
- 版が合わないエラーが返る → 新しい世代。示された版で話し直す
- それ以外のエラー、または無応答 → 旧世代。initialize の握手へ切り替える

このフォールバックを特定のエラーコードに結びつけてはいけません。 旧世代のサーバーが何を返すかは実装任せです。

プロセスが落ちたときも同じ考え方です。状態を持たないので、クライアントは起動し直して、失われたリクエストを投げ直すだけで済みます。ただし subscriptions/listen で開いていた通知の購読は張り直す必要があります。