Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Configurazione multi-server

Lezione 8 di 12 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Fonti multiple, singolo agente
  2. Sintassi: nulla di nuovo, solo voci multiple
  3. Le etichette diventano strutturali
  4. Come Grok seleziona un server
  5. Un agente di supporto end-to-end
  6. Punti chiave

Fonti multiple, singolo agente

Remote MCP esprime tutto il suo potenziale quando connetti Grok a più server contemporaneamente. Ciascuno mette a disposizione i propri strumenti e il modello arbitra tra di essi in base alla richiesta ricevuta. È proprio questo che distingue un agente capace di svolgere un’unica azione da un agente in grado di condurre un’indagine: verificare lo stato di un servizio, consultare la cronologia di un cliente e poi cercare una guida alla risoluzione dei problemi, senza che tu debba scrivere una singola riga di codice di orchestrazione.

Sintassi: nulla di nuovo, solo voci multiple

Non esiste alcuna modalità multi-server da attivare. Ti basta aggiungere più oggetti MCP all’elenco tools.

from xai_sdk.tools import mcp

tools = [
    mcp(server_url="https://mcp.deepwiki.com/mcp", server_label="deepwiki"),
    mcp(server_url="https://your-custom-tools.com/mcp", server_label="custom"),
    mcp(server_url="https://api.example.com/tools", server_label="api-tools"),
]

Lo stesso principio si applica alle Responses API in formato OpenAI, dove ogni server diventa un dizionario nell’elenco. Questa versione aggiunge le descrizioni, che come vedrai non sono più opzionali non appena utilizzi più di un server.

tools = [
    {
        "type": "mcp",
        "server_url": "https://mcp.deepwiki.com/mcp",
        "server_label": "deepwiki",
        "server_description": "Documentation for GitHub open-source projects"
    },
    {
        "type": "mcp",
        "server_url": "https://your-custom-tools.com/mcp",
        "server_label": "custom",
        "server_description": "Internal company tools"
    },
    {
        "type": "mcp",
        "server_url": "https://api.example.com/tools",
        "server_label": "api-tools",
        "server_description": "Data and analytics API"
    },
]

Le etichette diventano strutturali

Il parametro server_label, finora utile solo per la leggibilità, diventa qui essenziale. Prendi uno scenario molto comune: connetti la tua documentazione interna e DeepWiki, ed entrambi espongono uno strumento chiamato search. Senza etichette distinte, due strumenti portano lo stesso nome e Grok non ha modo di decidere. Con le etichette, deepwiki__search interroga la documentazione di GitHub mentre internal-docs__search cerca nella tua base di conoscenza: due strumenti chiaramente separati che il modello seleziona in base alle descrizioni e al flusso della conversazione.

Tre regole bastano per non incontrare mai problemi. Ogni etichetta deve essere unica nella configurazione. Deve riflettere la fonte dei dati piuttosto che la funzione tecnica, perché è la provenienza a distinguere i server tra loro, non ciò che fanno. E deve rimanere breve senza diventare intercambiabile. Il contrasto seguente illustra la differenza tra i due approcci:

# Buono: etichette descrittive e distinte
server_label="deepwiki"
server_label="crm"
server_label="jira"

# Cattivo: etichette ambigue
server_label="server1"
server_label="server2"
server_label="tools"

Le etichette della seconda serie sono una trappola latente. Funzionano il giorno in cui le scrivi, perché sai cosa contiene server1. Sei mesi dopo, rileggendo un log di incidente, nessuno lo sa più; e il modello, dal canto suo, non l’ha mai saputo.

Come Grok seleziona un server

Di fronte a più server, il modello incrocia quattro fonti di informazioni per decidere. Parte dalla richiesta dell’utente, ovvero da ciò che viene effettivamente chiesto. Consulta poi il campo server_description di ogni server, che gli indica a cosa serve ciascuno nel complesso. Scende di un livello ai nomi e alle descrizioni degli strumenti stessi, poiché ogni strumento ne porta di propri. Infine, tiene conto del contesto della conversazione, dato che i messaggi precedenti influenzano la selezione: se il cliente ti ha già fornito il numero di conto tre scambi prima, Grok sa di poter chiamare crm__get_customer senza chiederlo di nuovo.

Di queste quattro fonti, la seconda è quella su cui hai maggior controllo, ed è proprio per questo che le descrizioni diventano critiche in modalità multi-server. Senza descrizioni, Grok si basa solo sui nomi degli strumenti: un search contro un altro search, senza alcuna indicazione su cosa indicizzino. Gli errori di selezione che ne derivano sono tanto più confusi perché sembrano casuali: il modello sceglie correttamente metà delle volte, per fortuna.

Un agente di supporto end-to-end

Questa configurazione riunisce tutto quanto sopra in un caso d’uso completo.

tools = [
    mcp(
        server_url="https://kb.monentreprise.com/mcp",
        server_label="knowledge",
        server_description="Product knowledge base. Help articles, FAQ, troubleshooting guides.",
        allowed_tool_names=["search_articles", "get_article"]
    ),
    mcp(
        server_url="https://crm.monentreprise.com/mcp",
        server_label="crm",
        server_description="CRM. Customer history, previous tickets, account information.",
        authorization=f"Bearer {os.getenv('CRM_TOKEN')}",
        allowed_tool_names=["get_customer", "search_tickets", "get_ticket"]
    ),
    mcp(
        server_url="https://status.monentreprise.com/mcp",
        server_label="status",
        server_description="Service status. Ongoing incidents, scheduled maintenance.",
        allowed_tool_names=["get_current_status", "list_incidents"]
    ),
]

Un cliente scrive «il mio servizio non funziona più». Grok verifica prima se c’è un incidente in corso tramite status__get_current_status, consulta l’account del cliente con crm__get_customer per sapere di quale servizio si tratta, e poi cerca una guida alla risoluzione dei problemi tramite knowledge__search_articles. Questa sequenza non è scritta da nessuna parte nel tuo codice: deriva dalle descrizioni e dalla domanda posta. Nota anche che ogni server rimane limitato alle sue operazioni di lettura: la potenza del multi-server non elimina mai la necessità di una allowlist.

Punti chiave

  • Passa più oggetti MCP nell’elenco tools per il multi-server
  • Ogni server deve avere un server_label unico e descrittivo
  • I valori di server_description sono essenziali per guidare Grok verso il server corretto
  • Grok seleziona automaticamente il server appropriato in base alla richiesta e al contesto
  • Limita gli strumenti di ogni server con allowed_tool_names per ridurre il rumore