Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Autenticazione e header

Lezione 6 di 12 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Dimostra chi sta chiamando
  2. Il parametro authorization
  3. headers e extra_headers
  4. Una configurazione completa per la produzione
  5. Punti chiave

Dimostra chi sta chiamando

DeepWiki e altri server MCP pubblici accettano qualsiasi chiamante, il che è coerente con il loro scopo. Non appena esponi i tuoi strumenti, le cose cambiano: senza autenticazione, chiunque indovini l’URL può interrogare il tuo CRM o attivare i tuoi processi. xAI fornisce due parametri per gestire questo aspetto: authorization per il token di accesso e headers o extra_headers per tutto il resto.

Il parametro authorization

Invia un token di autenticazione al server MCP. Nello specifico, la stringa che fornisci viene inserita così com’è nell’header HTTP Authorization di ogni richiesta inviata a quel server.

mcp(
    server_url="https://api.example.com/mcp",
    server_label="internal",
    authorization="Bearer sk-your-token-here"
)

Il formato atteso dipende interamente dal server di destinazione, poiché authorization accetta qualsiasi stringa: è il server MCP a validarla, non xAI. Tre forme coprono quasi tutti i casi che incontrerai.

  • Bearer token: "Bearer sk-xxxx" — il più comune, utilizzato dalla maggior parte delle API REST
  • Chiave API: "ApiKey your-key" — alcuni servizi usano un prefisso personalizzato
  • Basic auth: "Basic base64(user:password)" — autenticazione di base codificata in base64

Poiché questo token accompagna ogni richiesta, la sua gestione richiede cautela. Non inserirlo mai direttamente nel codice sorgente: un segreto scritto in un file versionato finisce inevitabilmente in un repository, in un log o in uno screenshot. Usa sempre una variabile d’ambiente. Se il server lo consente, preferisci un token con ambito limitato che apra solo gli strumenti di cui hai effettivamente bisogno: questa è la controparte lato server della restrizione allowed_tool_names. E pianifica una rotazione regolare, specialmente in produzione, dove un token eterno è un token che prima o poi verrà compromesso.

import os

mcp(
    server_url="https://api.example.com/mcp",
    server_label="internal",
    authorization=f"Bearer {os.getenv('MCP_SERVER_TOKEN')}"
)

headers e extra_headers

Il token risponde alla domanda “chi sei”. Molti server necessitano di risposte aggiuntive: per quale organizzazione, su quale ambiente, con quale versione dell’API. Queste informazioni passano tramite il parametro headers, o extra_headers a seconda dell’SDK.

mcp(
    server_url="https://api.example.com/mcp",
    server_label="internal",
    authorization="Bearer sk-token",
    headers={
        "X-Organization-Id": "org-123",
        "X-Project-Id": "proj-456"
    }
)

Il caso più comune riguarda le piattaforme multi-tenant, dove lo stesso endpoint serve più clienti e si affida a un header per instradare la richiesta verso i dati corretti. Segue il versioning delle API, con un header come "X-API-Version": "2024-01" che blocca una versione specifica e ti protegge dalle modifiche del server. Alcuni sistemi si aspettano anche metadati di tracciamento—ID sessione, ID agente—per risalire all’origine delle chiamate, oppure header di limitazione della frequenza che determinano il piano di fatturazione applicato.

Il nome del parametro varia a seconda dell’interfaccia che utilizzi. L’SDK nativo xAI usa headers nella maggior parte dei casi; le API Responses in formato OpenAI potrebbero richiedere extra_headers, per evitare qualsiasi collisione con gli header che questo SDK gestisce automaticamente per sé. Il comportamento, tuttavia, è esattamente lo stesso: gli header vengono aggiunti a ogni richiesta al server MCP. Se le tue richieste partono senza i tuoi header, controlla prima il nome di questo parametro prima di cercare altrove.

Una configurazione completa per la produzione

Ecco come questi parametri si assemblano con quelli delle lezioni precedenti, in un caso realistico di server interno.

from xai_sdk.tools import mcp
import os

tools = [
    mcp(
        server_url="https://api.monentreprise.com/mcp",
        server_label="internal",
        server_description="Strumenti interni: CRM, documentazione, ticket",
        authorization=f"Bearer {os.getenv('INTERNAL_MCP_TOKEN')}",
        headers={
            "X-Organization-Id": os.getenv("ORG_ID"),
            "X-Environment": "production"
        },
        allowed_tool_names=["search_docs", "get_ticket", "search_contacts"]
    )
]

Questa configurazione si connette al server MCP interno tramite HTTPS, si autentica con un token Bearer memorizzato in una variabile d’ambiente, invia l’ID dell’organizzazione in un header e limita l’accesso a tre operazioni di lettura. Nota che ogni riga blocca un aspetto diverso: la crittografia protegge il trasporto, il token prova l’identità, l’header definisce l’ambito dei dati e la lista bianca limita i potenziali danni. Nessuno di questi livelli sostituisce gli altri.

Punti chiave

  • authorization invia il token di accesso al server MCP tramite l’header HTTP Authorization
  • Memorizza sempre i tuoi token nelle variabili d’ambiente, mai hardcoded nel codice
  • headers / extra_headers aggiungono header HTTP extra a ogni richiesta
  • Gli header servono per l’identificazione multi-tenant, il versioning delle API e il tracciamento
  • Combina autenticazione e restrizione degli strumenti per la massima sicurezza