Strumenti esterni e SDK supportati
In questa pagina
Tre punti di ingresso per lo stesso meccanismo
xAI espone MCP remoto attraverso tre interfacce. Sono rivolte a diversi sviluppatori: una per i nuovi progetti, un’altra per i progetti migrati e la terza per contesti d’uso specifici. Il comportamento di MCP è esattamente lo stesso in tutti e tre i casi; cambiano solo la sintassi di configurazione e gli strumenti periferici. La tua scelta dipende quindi dal tuo stack esistente, non dalle capacità del protocollo.
L’SDK nativo xAI
Questo è il metodo raccomandato da xAI. Fornisce un helper mcp() che condensa la configurazione in un’unica chiamata di funzione.
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://mcp.deepwiki.com/mcp")
],
include=["verbose_streaming"],
)
L’helper mcp() accetta tutti i parametri di configurazione MCP—URL, etichetta, descrizione, strumenti consentiti, autenticazione—e si occupa di formattarli correttamente per l’API. Questa è la sintassi più concisa e, cosa cruciale, quella in cui è meno probabile commettere errori, poiché nomi delle chiavi e annidamenti sono gestiti automaticamente. Scegli questa strada per un nuovo progetto senza vincoli di compatibilità, per qualsiasi prototipazione rapida e ogni volta che sfrutti funzionalità specifiche di xAI come lo streaming dettagliato visibile sopra.
Le API Responses, compatibili con OpenAI
Questa interfetta accetta esattamente il formato delle API OpenAI. Esiste per una ragione specifica: permettere a un team che ha già scritto la propria applicazione in questo formato di provare Grok senza riscrivere tutto. La modifica si limita alla chiave API e all’URL di base.
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1",
)
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input=[{"role": "user", "content": "Explain the React project"}],
tools=[{
"type": "mcp",
"server_url": "https://mcp.deepwiki.com/mcp",
"server_label": "deepwiki",
}],
)
Qui, il server MCP è dichiarato come elemento dell’array tools, con il tipo "mcp" e i parametri come coppie chiave-valore nello stesso oggetto. Nessun helper: scrivi il dizionario a mano, il che lascia più spazio a errori di battitura nei nomi delle chiavi.
Questa compatibilità ha un costo, che devi conoscere prima di costruirci sopra. Due parametri disponibili nell’SDK nativo non sono disponibili qui: require_approval, che ti permette di richiedere una validazione umana prima di eseguire uno strumento MCP, e connector_id, che gestisce i connettori OpenAI. Se il tuo agente gestisce operazioni sensibili e contavi sulla validazione manuale, questa limitazione è un blocco e dovrebbe riportarti verso l’SDK nativo xAI. Le API Responses rimangono la scelta giusta per una migrazione da OpenAI senza riscrittura, per un progetto multi-provider dove alterni Grok ad altri modelli e per un team già familiare con questo formato.
Le API Voice Agent
La terza interfaccia è progettata per gli agenti vocali. Lo scenario tipico è un assistente telefonico che, nel mezzo di una conversazione, deve consultare una base di conoscenze, verificare lo stato di un ordine o interrogare un sistema esterno—senza che il chiamante percepisca silenzi inspiegabili.
La configurazione MCP segue lo stesso formato degli altri SDK, con gli stessi parametri server_url, server_label e altri. La differenza sta in ciò che accade dopo la chiamata dello strumento: il risultato è integrato nel flusso di sintesi vocale invece di essere reso come testo. Questo influenza il modo in cui scrivi le descrizioni dei tuoi strumenti e strutturi le loro risposte, dato che l’utente non vedrà mai una tabella o un elenco: li ascolterà soltanto.
Cosa non cambia tra le interfacce
Qualunque sia l’SDK, la sequenza è la stessa. Grok scopre gli strumenti esposti dal server MCP, seleziona quello che corrisponde alla richiesta, formula la chiamata con i parametri corretti, quindi integra il risultato nella sua risposta. Nessuna delle tre interfacce rende il modello più o meno abile nella scelta di uno strumento.
Le differenze risiedono quindi altrove: concisione della sintassi, funzionalità periferiche disponibili—streaming dettagliato sull’SDK xAI, compatibilità di formato sulle API Responses, sintesi vocale sulle API Voice Agent—e i due parametri mancanti nel formato OpenAI. Decidi basandoti su questi criteri e non sbaglierai.
Punti chiave
- L’SDK nativo xAI con
mcp()è il metodo più semplice e completo - Le API Responses (formato OpenAI) facilitano la migrazione ma non supportano
require_approvalnéconnector_id - Le API Voice Agent collegano gli agenti vocali agli strumenti MCP
- Il comportamento di MCP è identico in tutti e tre i casi; cambia solo la sintassi
- Scegli in base al tuo stack esistente e alle tue esigenze specifiche