Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Descrizione e strumenti consentiti

Lezione 5 di 12 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Due leve opzionali, due effetti molto diversi
  2. server_description: dai contesto al modello
  3. allowed_tools: restringi l’ambito
  4. Perché limitare, anche quando tutto funziona
  5. Fai lavorare insieme i due parametri
  6. Punti chiave

Due leve opzionali, due effetti molto diversi

L’URL e l’etichetta bastano a stabilire la connessione, ma non dicono a Grok come utilizzare il server. Due parametri opzionali colmano questa lacuna e si completano a vicenda: server_description spiega a cosa serve il server, mentre allowed_tools—o allowed_tool_names a seconda dell’SDK—decide cosa gli è consentito toccare. Il primo guida, il secondo vincola.

server_description: dai contesto al modello

Questo parametro fornisce a Grok una descrizione in linguaggio naturale delle capacità del server. Il modello la usa per arbitrare: deve interrogare questo server, un altro, o nessuno dei due?

mcp(
    server_url="https://api.example.com/mcp",
    server_label="docs",
    server_description="Server di documentazione tecnica. Permette di cercare articoli, consultare guide e ottenere esempi di codice per l'API interna."
)

Senza questa descrizione, Grok ha solo i nomi e le descrizioni individuali degli strumenti esposti. Funziona, ma il modello ragiona senza una visione d’insieme: vede una raccolta di strumenti senza sapere cosa formano collettivamente. Una buona descrizione gli offre tre cose che nessun nome di strumento può trasmettere: quando questo server è rilevante rispetto a un altro, il tipo di richieste da instradare lì e—spesso trascurato, spesso decisivo—cosa il server non fa, evitando così chiamate destinate a fallire.

Scrivi questa descrizione come se stessi spiegando il servizio a un collega che si unisce al progetto. Sii specifico: “Database di documentazione tecnica del prodotto” è utile, mentre “Documentazione” non lo è. Nomina le azioni effettivamente possibili, come “permette di cercare, leggere e aggiornare i ticket”. E se l’ambito è limitato, dichiaralo chiaramente: “accesso in sola lettura, nessuna modifica” risparmierà al modello un tentativo fallito.

allowed_tools: restringi l’ambito

Per impostazione predefinita, collegare Grok a un server MCP inietta tutti gli strumenti che quel server espone nel contesto del modello, senza eccezioni. Su un CRM, ciò significa che creare, modificare ed eliminare contatti sono accessibili tanto quanto la ricerca.

mcp(server_url="https://api.example.com/mcp",
    server_label="crm")
# Grok vede TUTTI gli strumenti: create_contact, update_contact,
# delete_contact, search_contacts, export_data, ecc.

Il parametro allowed_tool_names inverte questo comportamento stabilendo una whitelist esplicita. Tutto ciò che non vi è incluso diventa invisibile al modello.

mcp(server_url="https://api.example.com/mcp",
    server_label="crm",
    allowed_tool_names=["search_contacts", "get_contact_details"])
# Grok vede solo search_contacts e get_contact_details

Perché limitare, anche quando tutto funziona

La prima ragione è la sicurezza, e segue il principio del minimo privilegio. Se la tua applicazione ha bisogno solo di leggere, non lasciare strumenti di modifica o eliminazione alla portata del modello. Un’iniezione di prompt riuscita—un’istruzione malevola inserita in un documento che Grok analizza—non può attivare un delete_contact che non è mai stato esposto. La whitelist trasforma un potenziale incidente in un non-evento.

# Sola lettura per un chatbot pubblico
allowed_tool_names=["search_database", "get_record", "format_data"]

La seconda ragione è la performance. Ogni strumento esposto occupa spazio nella finestra di contesto, poiché il suo nome, la descrizione e lo schema dei parametri devono starci dentro. Un server MCP che pubblica cinquanta strumenti consuma un volume considerevole prima ancora che l’utente abbia posto la sua domanda. Riducendosi a cinque strumenti davvero utili, recuperi quello spazio per ciò che conta: la conversazione stessa.

La terza ragione è la precisione. Più esteso è il catalogo, più il modello esita tra strumenti simili—e due strumenti con descrizioni analoghe producono scelte instabili da un’esecuzione all’altra. Un catalogo ristretto attorno al tuo caso d’uso rende la selezione significativamente più affidabile.

Fai lavorare insieme i due parametri

Il risultato diventa davvero pulito quando combini entrambi i parametri, a patto che raccontino la stessa storia.

mcp(
    server_url="https://api.example.com/mcp",
    server_label="crm",
    server_description="CRM in sola lettura. Cerca e visualizza contatti e aziende.",
    allowed_tool_names=["search_contacts", "get_contact", "search_companies", "get_company"]
)

Qui, la descrizione annuncia l’accesso in sola lettura e la whitelist lo garantisce tecnicamente. Attento alla situazione opposta, che accade più spesso di quanto pensi: una descrizione ereditata da una versione precedente che promette capacità di scrittura ora rimosse dalla whitelist. Il modello tenterà la chiamata, fallirà e passerai del tempo a caccia di un bug che non esiste. Rivedi sempre questi due parametri insieme, mai separatamente.

Punti chiave

  • server_description aiuta Grok a capire quando usare questo server MCP
  • Senza allowed_tools, tutti gli strumenti del server vengono iniettati nel contesto
  • Limitare gli strumenti rafforza sicurezza, performance e precisione
  • Combina descrizione e restrizione per un controllo ottimale
  • Scrivi la descrizione come una spiegazione in linguaggio naturale delle capacità del server