Kompletná konfigurácia servera MCP
Na tejto strane
Spájame všetko dokopy
S jednotlivými parametrami si sa už oboznámil. Táto lekcia ich spája do kompletných konfigurácií presne tak, ako ich budeš písať v praxi, pričom vždy ukážeme ekvivalent pre obe hlavné SDK. Cieľom nie je zavádzať nové koncepty, ale poskytnúť ti vzory, ktoré môžeš priamo adaptovať.
Tu je prehľad šiestich parametrov vrátane informácie, či sú povinné, alebo voliteľné.
| Parameter | Povinný | Úloha |
|---|---|---|
server_url | Áno | URL adresa servera MCP protokolu HTTPS |
server_label | Áno | Prefix pre volanie nástrojov |
server_description | Nie | Usmerňuje model Grok pri výbere servera |
allowed_tool_names | Nie | Obmedzuje dostupné nástroje |
authorization | Nie | Autentifikačný token |
headers | Nie | Dodatočné hlavičky HTTP |
Najjednoduchší prípad
Keď je server verejný a nevyžaduje si autentifikáciu, stačia dva parametre.
# xAI SDK
tools = [mcp(server_url="https://mcp.deepwiki.com/mcp", server_label="deepwiki")]
# Responses API (OpenAI)
tools = [{
"type": "mcp",
"server_url": "https://mcp.deepwiki.com/mcp",
"server_label": "deepwiki"
}]
Presne takto to napíšeš pre DeepWiki. Grok potom má prístup ku všetkým nástrojom servera, čo je tu prijateľné, keďže ide o verejnú službu len na čítanie. Akonáhle však server patrí tvojej organizácii, táto konfigurácia prestáva stačiť.
Interný server len na čítanie
Poďme o krok ďalej: podnikový CRM systém, ktorý musí agent vedieť dopytovať, no nikdy doňho zapisovať. Pridávajú sa tri parametre, každý z iného dôvodu – popis usmerňuje model, token preukazuje identitu a zoznam povolených nástrojov zakazuje operácie zápisu.
# xAI SDK
tools = [
mcp(
server_url="https://api.monentreprise.com/mcp",
server_label="crm",
server_description="Internal CRM. Contact and company lookup only.",
authorization=f"Bearer {os.getenv('CRM_TOKEN')}",
allowed_tool_names=["search_contacts", "get_contact", "list_companies"]
)
]
# Responses API (OpenAI)
tools = [{
"type": "mcp",
server_url": "https://api.monentreprise.com/mcp",
server_label="crm",
server_description": "Internal CRM. Contact and company lookup only.",
"authorization": f"Bearer {os.getenv('CRM_TOKEN')}",
"allowed_tool_names": ["search_contacts", "get_contact", "list_companies"]
}]
Porovnaj tieto dva bloky: obsah je totožný, mení sa len obal. Pomocná funkcia mcp() prijíma pomenované argumenty, zatiaľ čo formát OpenAI očakáva slovník s dodatočným kľúčom "type". To je jediný rozdiel, na ktorý si musíš pamätať pri prevode konfigurácie z jedného SDK do druhého.
Komplexná konfigurácia
Posledný krok: kombinácia všetkých šiestich parametrov v reálnom volaní pre xAI SDK.
import os
from xai_sdk import Client
from xai_sdk.tools import mcp
client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
model="grok-4.20-0309-reasoning",
tools=[
mcp(
server_url="https://tools.monentreprise.com/v1/mcp",
server_label="outils-internes",
server_description="Internal tools platform: document management, support tickets, knowledge base. Read-only access.",
authorization=f"Bearer {os.getenv('TOOLS_MCP_TOKEN')}",
headers={
"X-Organization-Id": os.getenv("ORG_ID"),
"X-Environment": "production",
"X-Request-Source": "grok-agent"
},
allowed_tool_names=[
"search_documents",
"get_document",
"search_tickets",
"get_ticket",
"search_knowledge_base"
]
)
],
include=["verbose_streaming"],
)
Všimni si vnútornú konzistenciu tohto príkladu. Popis avizuje prístup len na čítanie a päť povolených nástrojov sú výlučne operácie dopytovania – žiadny rozpor medzi tým, čo si model myslí, že môže robiť, a tým, čo konfigurácia dovoľuje. Hlavička X-Environment nastavená na production zabraňuje testovaciemu agentovi v zápise do ostrých dát a X-Request-Source urobí stopy na tvojom serveri použiteľnými, ak budeš potrebovať vypátrať pôvod neočakávanej požiadavky.
Kontrola pred nasadením
Pred akýmkoľvek nasadením do produkcie si over šesť bodov, z ktorých každý zodpovedá úskaliu, s ktorým sme sa v tomto kurze už stretli. URL adresa musí byť HTTPS s platným certifikátom, inak nič neprejde. Štítok musí zostať krátky, výstižný a v rámci konfigurácie jedinečný. Popis musí zodpovedať skutočne exponovaným nástrojom, inak sa model pokúsi o volania, ktoré sú odsúdené na zlyhanie. Povolené nástroje musia byť obmedzené na striktné minimum. Token musí pochádzať z premennej prostredia, nie zo zdrojového kódu. A dodatočné hlavičky musia presne zodpovedať tomu, čo očakáva tvoj server, vrátane správneho použitia veľkých a malých písmen – chyba vo veľkosti písmen pri X-Organization-Id spôsobí tiché zlyhanie, ktoré sa obzvlášť ťažko diagnostikuje.
Kľúčové poznatky
- Minimálna konfigurácia vyžaduje iba
server_urlaserver_label - Pridaj
server_descriptionna usmernenie modelu Grok, najmä pri nastaveniach s viacerými servermi - Obmedz prístup pomocou
allowed_tool_nameskvôli bezpečnosti a výkonu - Na autentifikáciu použi
authorizationaheaders - Obe SDK (natívne xAI aj OpenAI Responses) prijímajú rovnaké parametre, líši sa len syntax