約 5 分で読めます

x-mcp-header設計——引数をHTTPヘッダーで制御する

MCPサーバーをロードバランサーやWAFの背後に置くと、「リージョンやテナントで振り分けたい」「特定のパラメーターだけレート制限したい」という要件が出ます。ところがこれらの値はJSON-RPCの本文の中にあり、中継装置は本文を解析しないと読めません。この問題に対する仕様側の答えが、ツール引数をHTTPヘッダーへ写す x-mcp-header です。

関連する全体像はMCP 2026-07-28のステートレス化と移行手順で扱っています。本稿は、その中でも設計判断が必要な Mcp-Param-* に絞ります。

x-mcp-headerとは何か

x-mcp-headerは、ツールのinputSchemaに付ける拡張プロパティです。指定した引数の値を、クライアントがMcp-Param-{名前}ヘッダーへ写します。

サーバーは inputSchema の対象プロパティに "x-mcp-header": "Region" のように名前を書きます。クライアントは tools/call を送る際、その引数値を Mcp-Param-Region: us-west1 として HTTP ヘッダーに付与します。ドラフト仕様では、サーバー側の採用は任意、クライアント側の対応は必須です。

標準ヘッダーとの関係は次のとおりです。

ヘッダー由来用途
Mcp-MethodJSON-RPCの method操作種別での振り分け(全リクエスト必須)
Mcp-Nameparams.name / params.uriツール名・リソースURIでの振り分け
Mcp-Param-{名前}x-mcp-header を付けた引数業務パラメーターでの振り分け・制限

前の2つは仕様が固定した標準ヘッダーで、Mcp-Param-* だけがサーバーごとに設計できる拡張点です。

どの引数をヘッダーに出してよいのか

対象は文字列・整数・真偽値の3型だけです。number型は禁止で、整数は±2の53乗未満に限られます。配列や$refの内側にも付けられません。

仕様が定める x-mcp-header の制約は次のとおりです。

  • 値は空にできず、HTTPのfield-name形式(RFC 9110のtoken)に合致すること。CR・LFなどの制御文字は不可
  • 同一 inputSchema 内で、大文字小文字を無視して一意であること
  • 適用できるのは string / integer / boolean のみ。number は不可
  • スキーマのルートから properties だけをたどって到達できる位置に限る。items、oneOf・anyOf・allOf・not、if/then/else、$ref を経由する位置は不可

違反すると、ツール定義そのものが無効になります。Streamable HTTPを使うクライアントは、違反した定義を tools/list の結果から除外し、警告をログに残す仕様です。1つの注釈ミスで、そのツールだけが静かにクライアントから見えなくなります。サーバー公開前に、全ツールがクライアントの tools/list に現れることを確認してください。

設計上の最優先事項は秘匿情報の扱いです。仕様はパスワード・APIキー・トークン・個人情報に x-mcp-header を付けないよう求めています。ヘッダーの値はネットワーク上の中継装置から見えるためです。ヘッダーに出す候補は、リージョン、テナントID、環境名のような、分類・ルーティング用の低感度な値に限定します。

値はどうヘッダーに符号化されるのか

値がASCIIで安全に表せない場合、クライアントは「=?base64?…?=」形式でBase64化します。サーバーと中継装置は復号してから比較する必要があります。

引数値は、string はそのまま、integer は10進文字列、boolean は小文字の true / false に変換されます。HTTPヘッダー値は可視ASCIIとスペース、タブしか使えないため、次の場合はUTF-8のBase64で包みます。

Mcp-Param-Greeting: =?base64?SGVsbG8sIOS4lueVjA==?=

対象は、非ASCII文字、制御文字、前後の空白を含む値です。さらに、平文のASCIIでも =?base64? で始まり ?= で終わる値は、曖昧さを避けるため必ずBase64化されます。接頭辞と接尾辞は小文字で厳密に書く決まりです。

引数が null または未指定のときは、クライアントはヘッダーを付けません。サーバー側もヘッダーの存在を期待してはいけません。値が本文にあるのにヘッダーが無いリクエストは、非準拠クライアントとして拒否されます。

ゲートウェイでルール化するときは、この符号化を意識してください。日本語のテナント名を Mcp-Param-Tenant に出す設計にすると、ルールは常にBase64値と照合することになります。振り分けキーはASCIIの識別子(例:tenant-0042)にしておくと、ルールが単純になります。

ヘッダーと本文が食い違ったらどうなるのか

仕様は、ヘッダーを「本文の写し」として扱います。本文と食い違うリクエストは、HTTP 400とJSON-RPCエラー-32020(HeaderMismatch)で拒否されます。

ここが設計の核心です。ロードバランサーはヘッダーを見て振り分け、MCPサーバーは本文を見て実行します。両者が異なる値を信じると、「ヘッダーでは許可テナント、本文では別テナント」というすり抜けが成立します。仕様はこれを塞ぐため、本文を処理するサーバーに次を義務づけています。

  • ヘッダー値(Base64なら復号後)が本文の対応値と一致するか検証する
  • 不一致、必須ヘッダーの欠落、不正文字を検出したら、400と -32020 を返す
  • 整数は文字列比較ではなく数値で比較する(42.0 と 42 は同値)
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32020,
    "message": "Header mismatch: Mcp-Name header value 'foo' does not match body value 'bar'"
  }
}

クライアントは、必須の Mcp-Param-* が無い等で HeaderMismatch を受けたら tools/list を再取得し、スキーマの変更を確認してから再試行することが推奨されています。サーバー側でスキーマの注釈を変えるとクライアントのキャッシュが古くなるため、注釈の追加・変更は互換性に影響します。

中継装置のポリシーにも注意点があります。テナント別のレート制限などをヘッダーで行う中継装置は、MCP-Protocol-Version が「ヘッダーと本文の照合を要求する版」であることを確認し、古い版やヘッダー欠落のリクエストは信用せず拒否すべきです。照合が行われない経路を、ポリシーの迂回路にしないためです。

規模別の留意点(SMB / エンタープライズ)

SMB: 単一インスタンスのMCPサーバーでは、x-mcp-header は必須ではありません。まず Mcp-Method と Mcp-Name だけでログを取り、ツール別の呼び出し回数を把握するところから始めれば十分です。導入や定着の支援が必要ならKuuの運用管理サービスをご検討ください。

エンタープライズ: 複数リージョン・複数テナントを束ねる共有ゲートウェイでは、Mcp-Param-* が振り分けとレート制限の鍵になります。ゲートウェイでは、(1) 受信ヘッダーの許可リスト化、(2) 本文との照合を行う層の明確化、(3) 照合が及ばない旧版クライアントの遮断、の3点を設計に含めてください。大規模基盤での設計支援はKuu RDEで扱っています。

参考

まとめ

x-mcp-header は、ツール引数のうち string・integer・boolean をHTTPヘッダー Mcp-Param-{名前} へ写し、LBやWAFが本文を解析せずに制御できるようにする拡張です。制約に違反するとツール定義ごとクライアントから除外されること、秘匿情報を出さないこと、ヘッダーはあくまで本文の写しで不一致は -32020 で拒否されることが設計の要点です。MCPゲートウェイの設計や移行でお困りの場合は、Kuuにご相談ください。

関連記事

MCP Sampling——LLM補完委譲の設計とセキュリティA2A長時間タスク設計——ストリーミングとPush通知の使い分けA2A署名付きAgentCardの検証設計——JWSとJCSMCPのページネーション設計——cursorの正しい扱い方