ヘッダーパラメーター
ほとんどのサーバーでは、この機能は必要ありません。
サーバーの前段にあるゲートウェイやロードバランサーは、ボディを解析せずに読み取れる情報でしかルーティングできません。ツールの引数を x-mcp-header でマークすると、2026-07-28 の プロトコルバージョン を使うクライアントは、その値を HTTP ヘッダーとしても送信します。
引数をマークする
マークは、引数の JSON Schema に追加するキー 1 つです。MCPServer では、Field がそのキーを追加します。
server.py
from typing import Annotated
from pydantic import Field
from mcp.server import MCPServer
mcp = MCPServer("Bookshop")
@mcp.tool()
def check_stock(
title: str,
region: Annotated[str, Field(json_schema_extra={"x-mcp-header": "Region"})],
) -> str:
"""Count the copies of a book in one region's warehouses."""
return f"{title}: 3 copies in {region}."
2026-07-28の Streamable HTTP では、クライアントはボディに加えてMcp-Param-Regionを送信し、サーバーは両者が食い違う呼び出しを拒否します。- ツールを一覧取得していないクライアントは、マークを見たことがありません。そのためヘッダーを送信せず、呼び出しは拒否されます。この SDK の
Clientは、その場合にツールを一覧取得して呼び出しを 1 回だけ再送するので、先に一覧取得しておいても節約できるのはラウンドトリップ 1 回分だけです。 - それ以外の接続では、このアノテーションは無視されます。
関数は変わりません。region はこれまでどおり引数として渡されます。
マークできるもの
str、int、bool の引数です。それ以外は、ツールの登録時に InvalidSignature で拒否されます。
単一の型を持たない str | None も同様に拒否されます。省略可能な引数では、Pydantic の WithJsonSchema を使ってスキーマを明示する必要があります。
region: Annotated[str | None, WithJsonSchema({"type": "string", "x-mcp-header": "Region"})] = None
低レベルの Server の場合
こちらでは input_schema を手書きするので、キーをそのまま書き込みます。
server.py
from mcp.server import Server, ServerRequestContext
from mcp.types import (
CallToolRequestParams,
CallToolResult,
ListToolsResult,
PaginatedRequestParams,
TextContent,
Tool,
)
CHECK_STOCK = Tool(
name="check_stock",
description="Count the copies of a book in one region's warehouses.",
input_schema={
"type": "object",
"properties": {
"title": {"type": "string"},
"region": {"type": "string", "x-mcp-header": "Region"},
},
"required": ["title", "region"],
},
)
async def list_tools(ctx: ServerRequestContext, params: PaginatedRequestParams | None) -> ListToolsResult:
return ListToolsResult(tools=[CHECK_STOCK])
async def call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult:
args = params.arguments or {}
text = f"{args['title']}: 3 copies in {args['region']}."
return CallToolResult(content=[TextContent(type="text", text=text)])
server = Server("Bookshop", on_list_tools=list_tools, on_call_tool=call_tool)
app = server.streamable_http_app()
- アノテーションは何もチェックされません。不正なものもそのまま配信され、
2026-07-28のクライアントはそのツールを一覧から除外します。
名前からスキーマを取得する
ヘッダーをチェックするには、SDK は呼び出しをディスパッチする前にツールの入力スキーマを必要とします。get_tool_input_schema がない場合、SDK は引数を伴う呼び出しのたびに on_list_tools ハンドラーを実行してスキーマを取得します。マークされたツールがあるかどうかは関係ありません。
server.py
from typing import Any
from mcp.server import Server, ServerRequestContext
from mcp.types import (
CallToolRequestParams,
CallToolResult,
ListToolsResult,
PaginatedRequestParams,
TextContent,
Tool,
)
CHECK_STOCK = Tool(
name="check_stock",
description="Count the copies of a book in one region's warehouses.",
input_schema={
"type": "object",
"properties": {
"title": {"type": "string"},
"region": {"type": "string", "x-mcp-header": "Region"},
},
"required": ["title", "region"],
},
)
TOOLS = {CHECK_STOCK.name: CHECK_STOCK}
async def list_tools(ctx: ServerRequestContext, params: PaginatedRequestParams | None) -> ListToolsResult:
return ListToolsResult(tools=list(TOOLS.values()))
async def call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult:
args = params.arguments or {}
text = f"{args['title']}: 3 copies in {args['region']}."
return CallToolResult(content=[TextContent(type="text", text=text)])
def tool_input_schema(name: str) -> dict[str, Any] | None:
tool = TOOLS.get(name)
return tool.input_schema if tool else None
server = Server(
"Bookshop",
on_list_tools=list_tools,
on_call_tool=call_tool,
get_tool_input_schema=tool_input_schema,
)
app = server.streamable_http_app()
- この関数を渡すと、すでに手元にある情報から応答できます。
- チェックするものがないツールには
Noneを返してください。
まとめ
- ツールの引数に
x-mcp-headerを付けると、2026-07-28のクライアントはその値をMcp-Param-*HTTP ヘッダーとしても送信します。 - サーバーは、ヘッダーとボディが食い違う呼び出しを拒否します。
- マークできるのは
str、int、boolの引数だけです。それ以外の場合、MCPServerはInvalidSignatureを送出します。 - 低レベルの
Serverは何もチェックせず、クライアントはアノテーションが不正なツールを除外します。 get_tool_input_schemaを使うと、低レベルのServerが呼び出しのたびにon_list_toolsを実行するのを避けられます。
手書きで扱う Server API の残りの部分は、低レベルの Server で説明しています。