Configurație completă a serverului MCP
Pe această pagină
Integrarea tuturor elementelor
Ați întâlnit fiecare parametru izolat. Această lecție le reunește în configurații complete, exact așa cum le veți scrie în practică, prezentând de fiecare dată echivalentul în cele două SDK-uri principale. Scopul nu este introducerea unor concepte noi, ci oferirea unor modele pe care le puteți adapta direct.
Iată o prezentare generală a celor șase parametri, cu statutul lor obligatoriu sau opțional.
| Parametru | Obligatoriu | Rol |
|---|---|---|
server_url | Da | URL HTTPS al serverului MCP |
server_label | Da | Prefix pentru apelarea instrumentelor |
server_description | Nu | Ghidează Grok în selectarea serverului |
allowed_tool_names | Nu | Restricționează instrumentele accesibile |
authorization | Nu | Token de autentificare |
headers | Nu | Antete HTTP suplimentare |
Cel mai simplu caz
Doi parametri sunt suficienți atunci când serverul este public și nu necesită autentificare.
# 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"
}]
Acesta este exact codul pe care îl veți scrie pentru DeepWiki. Grok are astfel acces la toate instrumentele serverului, ceea ce rămâne acceptabil aici, deoarece este un serviciu public de tip read-only. De îndată ce serverul aparține organizației dumneavoastră, această configurație devine insuficientă.
Un server intern read-only
Să trecem la nivelul următor: un CRM enterprise pe care agentul trebuie să îl poată interoga, dar niciodată modifica. Se adaugă trei parametri, fiecare pentru un motiv distinct – descrierea ghidează modelul, token-ul dovedește identitatea, iar lista de允许 (allowlist) interzice scrierea.
# xAI SDK
tools = [
mcp(
server_url="https://api.monentreprise.com/mcp",
server_label="crm",
server_description="CRM intern. Doar căutare contacte și companii.",
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": "CRM intern. Doar căutare contacte și companii.",
"authorization": f"Bearer {os.getenv('CRM_TOKEN')}",
"allowed_tool_names": ["search_contacts", "get_contact", "list_companies"]
}]
Comparați cele două blocuri: conținutul este identic; doar wrapper-ul se schimbă. Funcția helper mcp() primește argumente numite; formatul OpenAI așteaptă un dicționar cu o cheie suplimentară "type". Aceasta este singura diferență de reținut atunci când traduceți o configurație de la un SDK la celălalt.
O configurație cuprinzătoare
Pasul final, cu toți cei șase parametri combinați într-un apel real către SDK-ul xAI.
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="Platformă de instrumente interne: gestionare documente, tichete de suport, bază de cunoștințe. Acces read-only.",
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"],
)
Observați coerența internă a acestui exemplu. Descrierea anunță un acces read-only, iar cele cinci instrumente permise sunt toate operațiuni de interogare – nicio contradicție între ceea ce modelul crede că poate face și ceea ce permite configurația. Antetul X-Environment setat la production împiedică un agent de testare să scrie în datele live, iar X-Request-Source va face urmele (traces) de pe server acționabile, dacă va trebui să urmăriți originea unei cereri neașteptate.
Verificare înainte de lansare
Șase puncte necesită o revizuire înainte de orice implementare în producție, iar fiecare corespunde unei capcane întâlnite anterior în acest curs. URL-ul trebuie să fie HTTPS cu un certificat valid; altfel, nimic nu va funcționa. Eticheta (label) trebuie să rămână scurtă, descriptivă și unică în cadrul configurației. Descrierea trebuie să corespundă instrumentelor expuse efectiv; altfel, modelul va încerca apeluri destinate eșecului. Instrumentele permise trebuie reduse la strictul necesar. Token-ul trebuie să provină dintr-o variabilă de mediu, nu din codul sursă. Iar antetele suplimentare trebuie să fie exact cele așteptate de serverul dumneavoastră, cu majuscule/minuscule corecte – o eroare de scriere la X-Organization-Id produce un eșec silențios, deosebit de dureros de diagnosticat.
Puncte cheie
- Configurația minimă necesită doar
server_urlșiserver_label - Adăugați
server_descriptionpentru a ghida Grok, în special în configurările cu mai multe servere - Restricționați accesul cu
allowed_tool_namespentru securitate și performanță - Utilizați
authorizationșiheaderspentru autentificare - Ambele SDK-uri (xAI nativ și OpenAI Responses) acceptă aceiași parametri, cu sintaxe diferite