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-Method | JSON-RPCの method | 操作種別での振り分け(全リクエスト必須) |
Mcp-Name | params.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で扱っています。
参考
- Tools(draft)| Model Context Protocol
- Streamable HTTP(draft)| Model Context Protocol
- SEP-2243: HTTP Standardization | Model Context Protocol
まとめ
x-mcp-header は、ツール引数のうち string・integer・boolean をHTTPヘッダー Mcp-Param-{名前} へ写し、LBやWAFが本文を解析せずに制御できるようにする拡張です。制約に違反するとツール定義ごとクライアントから除外されること、秘匿情報を出さないこと、ヘッダーはあくまで本文の写しで不一致は -32020 で拒否されることが設計の要点です。MCPゲートウェイの設計や移行でお困りの場合は、Kuuにご相談ください。
