Configurazione completa del server MCP
In questa pagina
Mettere tutto insieme
Hai incontrato ogni parametro singolarmente. Questa lezione li riunisce in configurazioni complete, esattamente come le scriverai nella pratica, mostrando ogni volta l’equivalente nei due SDK principali. L’obiettivo non è introdurre nuovi concetti, ma fornirti schemi che puoi adattare direttamente.
Ecco una panoramica dei sei parametri, con il loro stato obbligatorio o opzionale.
| Parametro | Obbligatorio | Ruolo |
|---|---|---|
server_url | Sì | URL HTTPS del server MCP |
server_label | Sì | Prefisso per la chiamata dello strumento |
server_description | No | Guida Grok nella selezione del server |
allowed_tool_names | No | Limita gli strumenti accessibili |
authorization | No | Token di autenticazione |
headers | No | Intestazioni HTTP aggiuntive |
Il caso più semplice
Due parametri sono sufficienti quando il server è pubblico e non richiede autenticazione.
# 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"
}]
Questo è esattamente ciò che scriverai per DeepWiki. Grok ha quindi accesso a tutti gli strumenti del server, il che rimane accettabile qui poiché si tratta di un servizio pubblico in sola lettura. Non appena il server appartiene alla tua organizzazione, questa configurazione diventa insufficiente.
Un server interno in sola lettura
Facciamo un passo avanti: un CRM aziendale che l’agente deve poter interrogare ma mai modificare. Si aggiungono tre parametri, ognuno per una ragione distinta: la descrizione guida il modello, il token prova l’identità e la lista bianca vieta le scritture.
# xAI SDK
tools = [
mcp(
server_url="https://api.monentreprise.com/mcp",
server_label="crm",
server_description="CRM interno. Solo ricerca contatti e aziende.",
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 interno. Solo ricerca contatti e aziende.",
"authorization": f"Bearer {os.getenv('CRM_TOKEN')}",
"allowed_tool_names": ["search_contacts", "get_contact", "list_companies"]
}]
Confronta i due blocchi: il contenuto è identico; cambia solo il contenitore. La funzione helper mcp() accetta argomenti nominati; il formato OpenAI si aspetta un dizionario con una chiave "type" aggiuntiva. Questa è l’unica differenza da ricordare quando traduci una configurazione da un SDK all’altro.
Una configurazione completa
Ultimo passo, con tutti e sei i parametri combinati in una chiamata reale all’SDK 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="Piattaforma strumenti interni: gestione documenti, ticket di supporto, base di conoscenza. Accesso in sola lettura.",
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"],
)
Nota la coerenza interna di questo esempio. La descrizione annuncia l’accesso in sola lettura e i cinque strumenti consentiti sono tutte operazioni di query: nessuna contraddizione tra ciò che il modello crede di poter fare e ciò che la configurazione permette. L’intestazione X-Environment impostata su production impedisce a un agente di test di scrivere sui dati reali, mentre X-Request-Source renderà le tracce del tuo server fruibili qualora tu debba risalire all’origine di una richiesta inaspettata.
Verifica prima del deploy
Sei punti meritano una revisione prima di qualsiasi deploy in produzione, e ciascuno corrisponde a una trappola incontrata in precedenza in questo corso. L’URL deve essere HTTPS con un certificato valido, altrimenti nulla funzionerà. L’etichetta deve rimanere breve, descrittiva e unica all’interno della configurazione. La descrizione deve corrispondere agli strumenti effettivamente esposti, altrimenti il modello tenterà chiamate destinate a fallire. Gli strumenti consentiti devono essere ridotti allo stretto minimo. Il token deve provenire da una variabile d’ambiente, non dal codice sorgente. E le intestazioni aggiuntive devono essere esattamente quelle che il tuo server si aspetta, con il corretto uso delle maiuscole: un errore di maiuscole su X-Organization-Id produce un fallimento silenzioso particolarmente doloroso da diagnosticare.
Punti chiave
- La configurazione minima richiede solo
server_urleserver_label - Aggiungi
server_descriptionper guidare Grok, specialmente in configurazioni multi-server - Limita con
allowed_tool_namesper sicurezza e prestazioni - Usa
authorizationeheadersper l’autenticazione - Entrambi gli SDK (xAI nativo e OpenAI Responses) accettano gli stessi parametri con sintassi diverse