A teljes MCP-kiszolgáló konfigurálása
Ezen az oldalon
Az egész összerakása
Minden paraméterrel külön-külön is találkoztál már. Ez a lecke egyetlen, teljes konfigurációba vonja össze őket, pontosan úgy, ahogy a gyakorlatban megírod majd, minden alkalommal bemutatva a megfelelő szintaxist a két fő SDK-ban. A cél nem új fogalmak bevezetése, hanem olyan minták átadása, amelyeket közvetlenül adaptálhatsz.
Íme a hat paraméter áttekintése, a kötelező vagy opcionális jellegük feltüntetésével.
| Paraméter | Kötelező | Szerep |
|---|---|---|
server_url | Igen | Az MCP-kiszolgáló HTTPS URL-címe |
server_label | Igen | Az eszközhívás előtagja |
server_description | Nem | Segíti a Grokot a kiszolgáló kiválasztásában |
allowed_tool_names | Nem | Korlátozza a hozzáférhető eszközöket |
authorization | Nem | Hitelesítési token |
headers | Nem | További HTTP-fejlécek |
A legegyszerűbb eset
Két paraméter is elegendő, ha a kiszolgáló nyilvános, és nem igényel hitelesítést.
# 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"
}]
Pontosan így fogod megírni a DeepWiki esetében. A Grok ezután hozzáfér a kiszolgáló összes eszközéhez, ami itt még elfogadható, mivel nyilvános, csak olvasható szolgáltatásról van szó. Amint a kiszolgáló a szervezetedhez tartozik, ez a konfiguráció már elégtelenné válik.
Egy csak olvasható belső kiszolgáló
Lépjünk egy szintet: egy vállalati CRM-rendszerre, amelyet az ügynöknek lekérdeznie kell tudnia, de soha nem módosíthat. Három paraméterrel bővül a lista, mindegyik más okból: a leírás irányítja a modellt, a token igazolja a személyazonosságot, az engedélyezési lista pedig megtiltja az írási műveleteket.
# 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"]
}]
Hasonlítsd össze a két blokkot: a tartalom azonos, csak a burkoló változik. Az mcp() segédfüggvény névvel ellátott argumentumokat vár, míg az OpenAI-formátum egy szótárat igényel egy plusz "type" kulccsal. Ez az egyetlen különbség, amit észben kell tartanod, amikor egyik SDK-ból a másikba fordítasz át egy konfigurációt.
Egy átfogó konfiguráció
Az utolsó lépés: mind a hat paraméter kombinálása egy valós hívásban az xAI SDK-ban.
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"],
)
Figyeld meg ennek a példának a belső következetességét. A leírás csak olvasható hozzáférést hirdet, és az öt engedélyezett eszköz mind lekérdezési művelet – nincs ellentmondás aközött, amit a modell szerint tehet, és amit a konfiguráció lehetővé tesz. A production értékre állított X-Environment fejléc megakadályozza, hogy egy tesztügynök élő adatokba írjon, az X-Request-Source pedig cselekvőképessé teszi a kiszolgálói naplókat, ha egyszer vissza kellene követned, honnan származott egy váratlan kérés.
Ellenőrzés telepítés előtt
Hat pontot érdemes átnézni bármilyen éles környezetbe történő telepítés előtt, és mindegyik egy olyan buktatónak felel meg, amellyel már találkoztál ebben a tanfolyamban. Az URL-nek HTTPS-nek kell lennie érvényes tanúsítvánnyal, különben semmi sem fog átmenni. A címkének rövidnek, leírónak és egyedinek kell maradnia a konfiguráción belül. A leírásnak egyeznie kell a ténylegesen közzétett eszközökkel, különben a modell olyan hívásokat próbál meg végrehajtani, amelyek eleve kudarcra vannak ítélve. Az engedélyezett eszközöket a szigorú minimumra kell csökkenteni. A tokennek környezeti változóból kell származnia, nem a forráskódból. A további fejléceknek pedig pontosan annak kell lenniük, amit a kiszolgálód elvár, helyes nagybetűzéssel – egy X-Organization-Id hibás nagybetűzése csendes hibát okoz, amelyet különösen fájdalmas diagnosztizálni.
Főbb megállapítások
- A minimális konfigurációhoz csak a
server_urlés aserver_labelszükséges - Add hozzá a
server_descriptionparamétert a Grok irányításához, különösen több kiszolgáló esetén - Korlátozz a
allowed_tool_namessegítségével a biztonság és a teljesítmény érdekében - Használd az
authorizationésheadersparamétereket a hitelesítéshez - Mindkét SDK (a natív xAI és az OpenAI Responses) ugyanazokat a paramétereket fogadja el, eltérő szintaxissal