Claude Media
MCPでMcp-MethodとMcp-Nameヘッダーが必須になった理由
MCPClaude Code解説

MCPでMcp-MethodとMcp-Nameヘッダーが必須になった理由

MCP仕様2026-07-28でStreamable HTTPのPOSTに必須化されたMcp-MethodとMcp-Nameヘッダー。HeaderMismatchErrorの発生条件とx-mcp-headerの使い方をまとめます。

読了目安 約11分

MCP仕様の2026-07-28改訂で、Streamable HTTPを使うすべてのPOSTリクエストにMcp-MethodとMcp-Nameという2つのHTTPヘッダーが必須になりました。JSON-RPCのリクエストボディに書かれている値をヘッダーにも複製する仕組みで、ロードバランサーや監視ツールが本文を解析せずにルーティング・監視できるようにするための変更です(SEP-2243)。ヘッダーとボディの値が食い違うと、サーバーはHeaderMismatchエラー(コード-32020)でリクエストを拒否します。

自分でStreamable HTTPのMCPサーバーを実装している、あるいはこれから実装する人にとっては、この2つのヘッダーの検証ロジックを正しく書けるかどうかが2026-07-28対応の合否を分けます。逆に、既存のHTTPサーバーが古いプロトコル版のまま動いている分には、今日から何かが壊れるわけではありません。

同じ2026-07-28改訂では、ツール定義のinputSchema・outputSchemaが受け入れるJSON Schemaのキーワード範囲そのものも広がっています(MCPのツール定義がJSON Schema 2020-12の全機能に対応)。後述のx-mcp-headerのようなスキーマ拡張プロパティも、この広がった許容範囲の上に成り立っています。

Mcp-MethodとMcp-Nameヘッダーが運ぶ情報

Mcp-MethodはJSON-RPCボディのmethodフィールドをそのまま複製したもので、Streamable HTTP経由のすべてのリクエストで必須です。Mcp-Nameはparams.name(tools/callのツール名)かparams.uri(resources/readのリソースURI)を複製したもので、tools/call・resources/read・prompts/getの3つのメソッドでのみ必須になります。

ヘッダー名複製元のフィールド必須になる条件
Mcp-Method複製元のフィールドmethod必須になる条件すべてのリクエスト
Mcp-Name複製元のフィールドparams.name または params.uri必須になる条件tools/call / resources/read / prompts/get

どちらもリクエストごとに毎回付与するもので、セッション単位で1度だけ送るような性格のヘッダーではありません。MCPの2026-07-28改訂はプロトコル全体をステートレス化しており、Mcp-Session-Idのような接続単位のヘッダーはむしろ廃止されています。1リクエスト1メタデータという設計思想の一部として、この2つのヘッダーを読むとわかりやすくなります。

HeaderMismatchErrorはどんな条件で起きるか

サーバーがリクエストボディを処理する場合、次のいずれかに該当すると400 Bad RequestとHeaderMismatch(-32020)エラーを返す義務があります。

  • 必須の標準ヘッダー(MCP-Protocol-Version・Mcp-Method・Mcp-Name)のいずれかが欠けている
  • ヘッダーの値がリクエストボディの対応する値と一致しない(Base64エンコードされている場合はデコードしてから比較)
  • ヘッダーの値に不正な文字が含まれている

エラーレスポンスの形はJSON-RPCの通常のエラーと同じです。

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32020,
    "message": "Header mismatch: Mcp-Name header value 'foo' does not match body value 'bar'"
  }
}

見落としやすいのは、整数パラメータの比較ルールです。仕様は「ヘッダー値とボディ値は文字列としてではなく数値として比較すべき」と定めており、42.0と42は一致とみなされます。ここを文字列比較で実装すると、正しいリクエストを誤って拒否してしまいます。

エラーコードの番号自体にも意味があります。JSON-RPC 2.0がサーバー実装依存のエラー用に予約する-32000から-32099の範囲のうち、MCP仕様は-32020から-32099を自分専用に確保しました。-32020(HeaderMismatch)・-32021(MissingRequiredClientCapability)・-32022(UnsupportedProtocolVersion)がこの範囲に入ります。それより手前の-32000から-32019は、この方針が導入される前に各SDKが独自に割り当てていたレガシー領域で、新しい実装はここに新規のコードを割り当ててはいけません。独自のエラーコードを作りたい場合は、JSON-RPCの予約範囲(-32768から-32000)の外に置く必要があります。

中継サーバー(ロードバランサーやゲートウェイ)の扱いにも注意点があります。認識できないMcp-Param-{Name}ヘッダーを受け取った中継サーバーは、それを転送しつつ無視する義務があり、勝手に落としてはいけません。また、ヘッダーを根拠にルーティングや制限をかける中継サーバーは、MCP-Protocol-Versionが実際に2026-07-28以降を示しているかを確認してから信用すべきだと明記されています。古いプロトコル版のリクエストのヘッダー値を検証なしに信用すると、なりすましの余地が生まれるためです。

x-mcp-headerでツール引数を独自ヘッダーに昇格させる

標準の2ヘッダーとは別に、MCPサーバーはツール定義のinputSchemaにx-mcp-headerという拡張プロパティを付けることで、任意のパラメータをHTTPヘッダーとしても送らせることができます(仕様の詳細と制約条件)。ヘッダー名はMcp-Param-{name}という形になります。

{
  "name": "execute_sql",
  "description": "Execute SQL on Google Cloud Spanner",
  "inputSchema": {
    "type": "object",
    "properties": {
      "region": {
        "type": "string",
        "x-mcp-header": "Region"
      },
      "query": { "type": "string" }
    },
    "required": ["region", "query"]
  }
}

このスキーマを受け取ったクライアントは、tools/callのリクエストにMcp-Param-Region: us-west1のようなヘッダーを自動で付け加えます。サーバー側での実装は任意ですが、x-mcp-headerが付いたツール定義を受け取ったクライアント側はこの機能に対応することが必須です。つまり、サーバーが仕様に沿ってこのアノテーションを使い始めた瞬間、対応済みのクライアントは自動でヘッダーを送るようになります。

値の変換にも細かい規定があります。文字列はそのまま、真偽値は小文字のtrue/false、整数は10進数表記に変換します。非ASCII文字や改行、前後の空白を含む値は=?base64?{Base64値}?=という記法でエンコードしなければなりません。Mcp-Nameヘッダーも同じ規則の対象です。

元の値理由エンコード後
"us-west1"理由ASCIIのみエンコード後Mcp-Param-Region: us-west1
"Hello, 世界"理由非ASCII文字を含むエンコード後Mcp-Param-Greeting: =?base64?SGVsbG8sIOS4lueVjA==?=
" padded "理由前後に空白エンコード後Mcp-Param-Text: =?base64?IHBhZGRlZCA=?=

x-mcp-headerを付けられるプロパティにも制約があります。propertiesキーだけをたどって到達できる静的なパスに限られ、配列(items)やoneOf・$refを経由するプロパティには付けられません。この制約に違反したツール定義は、Streamable HTTPのクライアント側で無効なツールとしてtools/listの結果から除外する義務があります。

クライアントが守るべき5ステップと大文字小文字の扱い

仕様は、Streamable HTTPでリクエストを組み立てるクライアントが踏むべき手順を5段階で定めています。

  1. ボディからmethod・params.name・params.uriの値を取り出す
  2. Mcp-Methodヘッダーと、該当すればMcp-Nameヘッダーを付与する
  3. ツールのinputSchemaからx-mcp-headerが付いたプロパティを探し、値が存在する場合のみ取り出す
  4. 値をエンコード規則に従って変換する
  5. Mcp-Param-{Name}ヘッダーとして付与する

値がなければヘッダー自体を省略する点が徹底されており、nullや未指定のパラメータに空のヘッダーを送ってはいけません。

ヘッダー名(RFC 9110でいう「フィールド名」)は大文字小文字を区別せず比較しますが、ヘッダーの値は区別されます。つまりmcp-methodとMcp-Methodは同じヘッダーとして扱われますが、Mcp-Method: tools/callとMcp-Method: Tools/Callは別の値として検証されます。メソッド名やツール名は仕様上ケースに意味があるため、ここを混同すると本来一致するはずのリクエストがHeaderMismatchで弾かれます。

サーバーが必須のMcp-Param-*ヘッダーの欠落や不一致でHeaderMismatchエラーを返した場合、クライアントはtools/listを呼び直してツール定義のinputSchemaが変わっていないかを確認したうえで、適切なヘッダーを付け直して元のリクエストを再送すべきだとされています。ツール定義がサーバー側で更新された直後に起きやすい状況で、キャッシュしたスキーマのまま送り続けるクライアント実装だとこのエラーから抜け出せなくなります。

実装者は何をすればいいか

必須ヘッダーへの対応が誰にどれくらい効くかは、どの立場でMCPに関わっているかで変わります。

立場対応の要否内容
Streamable HTTPサーバーの自作者対応の要否対応必須内容Mcp-Method/Mcp-Nameの検証ロジックとエラーコードの実装
x-mcp-headerを使いたいサーバー対応の要否任意(使うなら仕様準拠)内容スキーマ拡張とヘッダー抽出ロジック
stdioサーバーの自作者対応の要否対応不要内容ヘッダー層自体が存在しない
Claude Codeでサーバーを使うだけの利用者対応の要否対応不要内容クライアント側の実装はSDKが担う

自作サーバーを持たず、公開されているMCPサーバーをClaude Codeにつなぐだけの利用者には、直接の作業は発生しません。関係してくるのは、自分でStreamable HTTPのサーバーを書いている、または書こうとしている場合です。

Claude Codeとの接続で意識しておきたいのは、ネゴシエーションのタイミングです。Claude Code v2.1.232以降のv2ランタイムは、HTTPサーバーとclaude.aiコネクタサーバーに対しては標準で2026-07-28への対応可否を尋ね、対応していればそちらを使います。つまり、自作のStreamable HTTPサーバーのSDKを2026-07-28対応版に上げた瞬間、Claude Code側は特別な設定なしにこの新しいヘッダー要件込みの通信へ切り替わります。stdioサーバーは扱いが異なり、環境変数MCP_PROTOCOL_NEGOTIATIONをautoに設定しない限り、Claude Codeは古いハンドシェイクのまま接続します。

Mcp-Method/Mcp-Nameヘッダーの必須化で「本文を見ないルーティング」が仕様上できるようになる

この変更が想定しているのは、1台のstdioサーバーを個人で動かすような使い方ではありません。複数のバックエンドにリクエストを振り分けるロードバランサーや、テナントごとに課金・監視をかけるゲートウェイの手前で、JSON本文をパースせずにメソッド名やツール名だけを見て処理を分けたい運用です。

MCPは当初、AIアプリケーションとローカルツールをつなぐ軽量なプロトコルとして始まりました。今回のヘッダー必須化は、それが複数クライアント・複数バックエンドを前提にした本番運用のWeb APIへと性格を変えつつあることの表れです。個人の自作サーバー1台にとっては過剰に見える要件でも、事業者が大量のMCPトラフィックを裏で振り分ける段階に来ると、本文を見ないルーティングという発想そのものが必要になります。

まとめ

Streamable HTTPのPOSTリクエストには、2026-07-28仕様からMcp-MethodとMcp-Nameが必須になりました。値がボディと食い違えばHeaderMismatch(-32020)エラーで拒否され、x-mcp-headerを使えば任意のツールパラメータも同じ仕組みでヘッダー化できます。対応が必要になるのは自分でStreamable HTTPサーバーを実装する側で、Claude Codeを使うだけの利用者に追加の作業はありません。自作サーバーのSDKを2026-07-28対応に上げる予定があるなら、ヘッダー検証のロジックを仕様どおりに実装できているかを先に確認しておくと安全です。

MCP自体の仕組みや3層構造から知りたい場合はMCPとはを、Claude Codeでのclaude mcp addによるサーバー追加やスコープの使い分けはClaude Code MCP設定ガイドを参照してください。自作サーバーの作り方全般はMCPサーバー自作ガイドにまとめています。

この記事を共有:XはてブLinkedIn

関連する記事

MCP をもっと見る →