Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Configurazione completa del server MCP

Lezione 7 di 12 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Mettere tutto insieme
  2. Il caso più semplice
  3. Un server interno in sola lettura
  4. Una configurazione completa
  5. Verifica prima del deploy
  6. Punti chiave

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.

ParametroObbligatorioRuolo
server_urlSìURL HTTPS del server MCP
server_labelSìPrefisso per la chiamata dello strumento
server_descriptionNoGuida Grok nella selezione del server
allowed_tool_namesNoLimita gli strumenti accessibili
authorizationNoToken di autenticazione
headersNoIntestazioni 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_url e server_label
  • Aggiungi server_description per guidare Grok, specialmente in configurazioni multi-server
  • Limita con allowed_tool_names per sicurezza e prestazioni
  • Usa authorization e headers per l’autenticazione
  • Entrambi gli SDK (xAI nativo e OpenAI Responses) accettano gli stessi parametri con sintassi diverse