헤더 매개변수
기계 번역
이 페이지는 영어 문서를 자동으로 번역한 것이며, 영어 페이지가 기준이 되는 정식 버전입니다. 어색하거나 잘못된 부분이 있다면 번역 페이지에서 제보하는 방법을 확인하세요.
대부분의 서버에는 필요 없는 내용입니다.
서버 앞에 놓인 게이트웨이나 로드 밸런서는 본문을 파싱하지 않고 읽을 수 있는 정보만으로 라우팅할 수 있습니다. 도구 인수에 x-mcp-header를 표시하면 2026-07-28 프로토콜 버전을 사용하는 클라이언트가 그 값을 HTTP 헤더로도 보냅니다.
인수 표시하기
표시는 인수의 JSON Schema에 추가하는 키 하나입니다. 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는 이때 도구 목록을 조회한 뒤 호출을 한 번 다시 보내므로, 목록을 먼저 조회해도 왕복 한 번을 아낄 뿐입니다. - 그 밖의 모든 연결은 이 애너테이션을 무시합니다.
함수는 바뀌지 않습니다. 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에서 다룹니다.