Ana içeriğe geç

Başlık parametreleri

Makine çevirisi

Bu sayfa İngilizce dokümantasyondan otomatik olarak çevrildi; esas alınması gereken sürüm İngilizce sayfadır. Yanlış görünen bir şey varsa, nasıl bildireceğinizi Çeviriler sayfası açıklar.

Çoğu sunucunun buna hiç ihtiyacı olmaz.

Sunucunun önündeki bir ağ geçidi veya yük dengeleyici, yalnızca gövdeyi ayrıştırmadan okuyabildiği bilgilere göre yönlendirme yapabilir. Bir araç argümanını x-mcp-header ile işaretleyin; 2026-07-28 protokol sürümünü kullanan istemciler bu argümanın değerini HTTP başlığı olarak da gönderir.

Bir argümanı işaretleme

İşaret, argümanın JSON Schema'sındaki fazladan tek bir anahtardır. MCPServer'da bunu oraya Field koyar:

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 sürümünde Streamable HTTP üzerinden istemci, gövdeyle birlikte Mcp-Param-Region başlığını da gönderir; ikisi uyuşmazsa sunucu çağrıyı reddeder.
  • Aracı listelememiş bir istemci işareti hiç görmemiştir: başlık göndermez ve çağrı reddedilir. Bu SDK'nın Client'ı bunun üzerine araçları listeler ve çağrıyı bir kez yeniden gönderir; yani önce listelemek yalnızca bir gidiş-dönüş kazandırır.
  • Diğer tüm bağlantılar bu ek açıklamayı yok sayar.

Fonksiyonunuz değişmez: region yine argüman olarak gelir.

İşaretlenebilecek argümanlar

str, int ve bool argümanlar. Bunların dışındaki her şey, araç kaydedilirken InvalidSignature ile reddedilir.

Tek bir türü olmayan str | None da buna dahildir. İsteğe bağlı bir argümanın şeması, pydantic'in WithJsonSchema'sıyla açıkça yazılmalıdır:

region: Annotated[str | None, WithJsonSchema({"type": "string", "x-mcp-header": "Region"})] = None

Düşük seviyeli Server'da

Orada input_schema'yı elle yazarsınız, bu yüzden anahtar doğrudan içine yazılır:

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()
  • Ek açıklamayı sizin yerinize hiçbir şey denetlemez: geçersiz olanı da sunulur ve 2026-07-28 istemcileri aracı listelerine almaz.

Ada göre şemalar

Başlığı denetlemek için SDK'nın, çağrıyı iletmeden önce aracın girdi şemasına ihtiyacı vardır. get_tool_input_schema yoksa SDK bu şemayı, herhangi bir araç işaretli olsun olmasın, argüman taşıyan her çağrıda on_list_tools işleyicinizi çalıştırarak alır.

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()
  • Elinizde zaten olan bilgiden yanıt vermek için fonksiyonu geçirin.
  • Denetlenecek bir şeyi olmayan araç için None döndürün.

Özet

  • Bir araç argümanındaki x-mcp-header, 2026-07-28 istemcilerinin bu argümanı Mcp-Param-* HTTP başlığı olarak yinelemesini sağlar.
  • Sunucu, başlığı ile gövdesi uyuşmayan çağrıyı reddeder.
  • Yalnızca str, int ve bool argümanlar işaretlenebilir. MCPServer, bunların dışındaki her şey için InvalidSignature fırlatır.
  • Düşük seviyeli Server hiçbir şeyi denetlemez; istemciler de ek açıklaması geçersiz olan aracı eler.
  • get_tool_input_schema, düşük seviyeli Server'ın her çağrıda on_list_tools'u çalıştırmasını önler.

Elle yazılan Server API'sinin geri kalanı Düşük seviyeli Server sayfasında.