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

> x-mcp-headerはツール引数をMcp-ParamヘッダーへMirrorし、LBやWAFが本文を解析せず制御できる仕組みです。制約・Base64符号化・-32020検証までを整理します。

- Canonical: https://kuucorp.com/blog/mcp-x-mcp-header-param-gateway-routing-design/
- Date: 2026-10-25
- Last modified: 2026-10-25
- Publisher: Kuu株式会社 (https://kuucorp.com)

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

関連する全体像は[MCP 2026-07-28のステートレス化と移行手順](/blog/mcp-2026-stateless-spec-migration-guide/)で扱っています。本稿は、その中でも設計判断が必要な `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で包みます。

```text
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` は同値）

```json
{
  "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の運用管理サービス](/services/ai-ops/)をご検討ください。

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

## 参考

- [Tools（draft）| Model Context Protocol](https://modelcontextprotocol.io/specification/draft/server/tools)
- [Streamable HTTP（draft）| Model Context Protocol](https://modelcontextprotocol.io/specification/draft/basic/transports/streamable-http)
- [SEP-2243: HTTP Standardization | Model Context Protocol](https://modelcontextprotocol.io/seps/2243-http-standardization)

## まとめ

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