server_url e server_label
In questa pagina
Aggiornato il 3 novembre 2026 sulla base della pagina Remote MCP Tools di xAI:
server_labelaggiunge un prefisso alle chiamate degli strumenti, ma la documentazione non specifica il formato esatto del prefisso; la notazionelabel__toolutilizzata in questo corso è una convenzione di lettura: verifica il formato effettivo nelle risposte della tua API. Fonte: Remote MCP Tools.
I due parametri indispensabili
Ogni connessione tra Grok e un server MCP remoto si basa su due parametri: server_url e server_label. Sono non negoziabili: senza di essi, l’API rifiuta la richiesta prima ancora di tentare qualsiasi operazione. Tutti gli altri parametri che incontrerai in seguito affinano questa base, ma non la sostituiscono mai.
server_url: L’indirizzo esatto dell’endpoint
Il parametro server_url contiene l’URL completo del server MCP a cui Grok deve connettersi, e questo URL segue regole rigorose.
La prima regola è HTTPS. L’URL deve iniziare con https:// e xAI rifiuta qualsiasi connessione HTTP non crittografata. Il motivo è semplice: gli scambi tra Grok e il server MCP trasportano le richieste dei tuoi utenti, i risultati degli strumenti e talvolta il token di autenticazione stesso. Lasciar circolare questi dati in chiaro sarebbe indifendibile.
# Corretto
mcp(server_url="https://mcp.deepwiki.com/mcp")
# Rifiutato dall'API
mcp(server_url="http://mcp.deepwiki.com/mcp")
La seconda regola riguarda la precisione del percorso. L’URL deve puntare all’endpoint MCP, non alla radice del dominio. Quasi tutti i server espongono il proprio endpoint su un percorso dedicato e la convenzione varia da uno all’altro. Ecco tre forme valide che incontrerai:
https://mcp.deepwiki.com/mcp
https://api.example.com/mcp
https://tools.monentreprise.com/v1/mcp
La terza regola deriva dalle prime due: localhost e gli indirizzi IP privati sono esclusi. Il server deve essere raggiungibile dall’infrastruttura di xAI, su un dominio pubblico, con un certificato SSL valido. Questo solleva una domanda concreta durante lo sviluppo, poiché il server MCP che stai scrivendo gira sulla tua macchina. La soluzione abituale è utilizzare un tunnel, come ngrok o Cloudflare Tunnel, che espone la tua istanza locale dietro un URL HTTPS pubblico per la durata dei tuoi test.
server_label: L’identità del server nella conversazione
Il server_label è un identificatore breve che Grok utilizza per aggiungere un prefisso alle chiamate degli strumenti provenienti da questo server. Il suo ruolo è duplice: rendere le tracce leggibili ed eliminare ogni ambiguità quando coesistono più server.
La documentazione di xAI afferma che l’etichetta aggiunge un prefisso alle chiamate degli strumenti di questo server, senza specificare il formato esatto del prefisso. In questo corso, indichiamo uno strumento search_docs del server deepwiki come deepwiki__search_docs, per leggibilità: verifica il formato effettivo nelle risposte dell’API prima di costruire logica su di esso.
mcp(
server_url="https://mcp.deepwiki.com/mcp",
server_label="deepwiki"
)
# Le chiamate degli strumenti da questo server avranno il prefisso "deepwiki"
Tre criteri guidano la scelta di una buona etichetta. Deve essere breve, poiché si aggiunge al nome di ogni chiamata e un’etichetta verbosa gonfia inutilmente i tuoi log. Deve essere descrittiva, in modo che la fonte di una chiamata sia leggibile a colpo d’occhio senza consultare la configurazione. Deve essere unica nella tua configurazione, altrimenti non potrai distinguere tra due server. Gli esempi seguenti soddisfano questi tre requisiti:
server_label="deepwiki" # Documentazione GitHub
server_label="crm" # Sistema di gestione clienti
server_label="jira" # Tracciamento ticket
server_label="search" # Motore di ricerca interno
Questo diventa molto più tangibile non appena colleghi più server alla stessa sessione. Supponi che la tua documentazione interna e DeepWiki espongano entrambi uno strumento chiamato search. Senza etichette distinte, i nomi degli strumenti entrano in conflitto e Grok non ha modo di sapere quale prendere di mira. Con le etichette, i due strumenti ricevono prefissi diversi, qui indicati come deepwiki__search e internal-docs__search, e la confusione scompare. Rivedrai questo punto nella lezione dedicata ai server multipli.
Configurazione minima in entrambi gli SDK
Insieme, questi due parametri sono sufficienti per far funzionare un server MCP pubblico. Con l’SDK nativo xAI:
from xai_sdk.tools import mcp
tools = [
mcp(
server_url="https://mcp.deepwiki.com/mcp",
server_label="deepwiki"
)
]
E l’esatto equivalente con le Responses API in formato OpenAI:
tools = [{
"type": "mcp",
"server_url": "https://mcp.deepwiki.com/mcp",
"server_label": "deepwiki",
}]
Punti chiave
server_urleserver_labelsono gli unici due parametri obbligatori- L’URL deve essere HTTPS con un certificato SSL valido, niente localhost
- L’etichetta aggiunge un prefisso a tutte le chiamate degli strumenti di questo server (il formato esatto non è documentato; questo corso lo indica come
label__tool) - Scegli etichette brevi, descrittive e uniche per ogni server
- L’etichetta è essenziale per i server multipli per evitare conflitti di nomi