Vai al contenuto principale
Italiano— Scegli una lingua
Menu

OAuth 2.0 per i server MCP

Lezione 8 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Perché OAuth in MCP?
  2. Come funziona il flusso
  3. Configurazione di OAuth sul client Python
  4. Privilegio minimo, applicato agli scope
  5. Archiviazione e rinnovo dei token
  6. Quando un token semplice è sufficiente
  7. Cosa gestisce Vibe per te
  8. Punti chiave

Aggiornamento 2 novembre 2026 — Le Chat è ora Vibe. Dal 28 maggio 2026, Le Chat è stato rinominato Vibe (sempre all’indirizzo chat.mistral.ai): un unico agente per lavoro e codice, che mantiene le tue conversazioni, impostazioni e abbonamenti. L’esperienza legacy di Le Chat rimane accessibile nella modalità Chat; nella modalità Work, gli agenti sono diventati competenze (invocate con @), le memorie sono ora la base di conoscenza e la ricerca approfondita è la competenza Deep Research. I piani si chiamano ora Mistral Free, Pro, Team ed Enterprise. Questa lezione utilizza il nome Vibe; alcuni menu qui descritti potrebbero aver cambiato nome o posizione. Addendum 3 novembre: l’esempio precedente chiamava requires_auth, set_oauth_params o get_token_from_auth_response su MCPClientStreamableHTTP, che non possiede nessuno di questi metodi nell’SDK mistralai 3.7.0; ora segue l’esempio ufficiale async_conversation_run_mcp_remote_auth.py, utilizzando MCPClientSSE. Fonte: client-python, esempi MCP.

Perché OAuth in MCP?

Finché il tuo server MCP si limita a convertire valute o interrogare un database pubblico, l’identità non è un problema. Diventa critica nel momento in cui il server tocca email, calendari, repository GitHub o ticket Linear: non lavora più per sé stesso, ma agisce per conto di un utente specifico. Un token statico situato in un file di configurazione non dice nulla su questo consenso. Non specifica chi ha autorizzato cosa, per quanto tempo, né fino a dove si estendono i diritti concessi. OAuth 2.0 colma esattamente queste tre lacune: consenso esplicito, diritti limitati dagli scope e rinnovo sicuro.

Ricorda i tre livelli di autenticazione trattati in precedenza. Il primo, nessuna auth, è adatto a un URL pubblico senza dati sensibili. Il secondo, token statico, corrisponde a una chiave API generata manualmente, come un Personal Access Token di GitHub. Il terzo, OAuth 2.0, aggiunge l’intero flusso di consenso con scope e token di aggiornamento. Passare dal secondo al terzo livello non riguarda la sofisticazione tecnica, ma la responsabilità: una volta che più persone utilizzano il tuo server sui propri dati, un token condiviso diventa un buco nella sicurezza.

Come funziona il flusso

Quando un utente collega un server MCP con OAuth in Vibe, sette passaggi si concatenano. Vale la pena visualizzarli una volta per tutte:

1. L'utente clicca su "Connetti" in Vibe
       ↓
2. Vibe reindirizza alla pagina di autorizzazione del servizio
   (es. GitHub, Google, Linear)
       ↓
3. L'utente concede i permessi richiesti (scope)
       ↓
4. Il servizio restituisce un codice di autorizzazione al callback
       ↓
5. Il client scambia il codice per un token di accesso + token di aggiornamento
       ↓
6. Il token di accesso viene utilizzato per ogni chiamata MCP
       ↓
7. Quando il token di accesso scade, il token di aggiornamento ne ottiene uno nuovo

In questa coreografia circolano tre token diversi, spesso confusi tra loro. Il codice di autorizzazione è temporaneo e monouso: viene scambiato immediatamente per i token reali. Il token di accesso accompagna poi ogni richiesta e ha vita breve, tipicamente un’ora. Il token di aggiornamento, infine, serve solo a ottenere un nuovo token di accesso senza chiedere nuovamente il consenso all’utente. Questa breve durata del token di accesso è una salvaguardia: se un token viene compromesso, la sua finestra di sfruttamento rimane stretta.

Configurazione di OAuth sul client Python

L’SDK Mistral supporta questo flusso con l’helper build_oauth_params e alcuni metodi del client MCP. Fai attenzione alla scelta del client: nell’SDK mistralai 3.7.0, questi metodi OAuth esistono solo sul client SSE, MCPClientSSE, che è ciò che l’esempio ufficiale dell’SDK utilizza con il server Linear; MCPClientStreamableHTTP non ne possiede alcuno.

from mistralai.extra.mcp.auth import build_oauth_params
from mistralai.extra.mcp.sse import MCPClientSSE, SSEServerParams

REDIRECT_URL = "http://localhost:16010/oauth/callback"
SERVER_URL = "https://mcp.linear.app/sse"

mcp_client = MCPClientSSE(sse_params=SSEServerParams(url=SERVER_URL))

async def connect():
    global mcp_client
    if not await mcp_client.requires_auth():
        return mcp_client  # Il server è aperto: nulla da fare

    # 1. Scoprire gli endpoint OAuth del server
    #    (e registrare dinamicamente il client se non viene fornito client_id)
    oauth_params = await build_oauth_params(
        mcp_client.base_url,
        redirect_url=REDIRECT_URL,
    )
    mcp_client.set_oauth_params(oauth_params=oauth_params)

    # 2. Costruire l'URL di consenso e aprirlo nel browser
    login_url, state = await mcp_client.get_auth_url_and_state(REDIRECT_URL)
    print(f"Autorizza l'accesso: {login_url}")

    # 3. Intercettare il callback, quindi scambiare il codice per un token,
    #    utilizzando un client ricreato dai parametri OAuth salvati
    auth_response = await wait_for_callback()  # piccolo server HTTP locale
    mcp_client = MCPClientSSE(sse_params=SSEServerParams(url=SERVER_URL), oauth_params=oauth_params)
    token = await mcp_client.get_token_from_auth_response(
        auth_response["url"],
        redirect_url=REDIRECT_URL,
        state=state,
    )
    mcp_client.set_auth_token(token)
    return mcp_client

build_oauth_params fa due cose e solo due: legge i metadati OAuth pubblicati dal server MCP e registra dinamicamente un client se non passi né client_id né client_secret. Il resto del flusso spetta a te: aprire l’URL di consenso, raccogliere il callback sulla tua porta redirect_url, scambiare il codice per un token. L’SDK non nasconde questi passaggi; li fornisce come strumenti, ed è proprio questa scomposizione che ti permette di collegare il callback a un’app web piuttosto che a uno script.

Privilegio minimo, applicato agli scope

Gli scope definiscono cosa può fare il tuo server una volta ottenuto il consenso, e la schermata di consenso li mostra all’utente. Chiedere in modo ampio è allettante: evita di dover tornare indietro se sorge una necessità. È anche il modo migliore per spaventare un utente prudente ed esporre inutilmente il suo account. Confronta:

# Male: troppi permessi
scope=["repo", "admin:org", "delete_repo", "user"]

# Bene: giusto il necessario per creare issue
scope=["repo:issues", "read:user"]

Un server che crea issue non ha alcun motivo di eliminare repository o amministrare l’organizzazione. Ogni servizio pubblica la propria nomenclatura di scope: consulta la documentazione OAuth del servizio di destinazione invece di indovinare per analogia.

Archiviazione e rinnovo dei token

I token che ottieni valgono quanto le credenziali che sostituiscono e meritano la stessa cura. Scrivili in un file dedicato con permessi di sistema ristretti:

import os
import json
from pathlib import Path

TOKEN_FILE = Path.home() / ".mcp" / "tokens.json"

def save_tokens(service: str, access_token: str, refresh_token: str):
    """Salva i token in modo sicuro."""
    TOKEN_FILE.parent.mkdir(parents=True, exist_ok=True)
    tokens = {}
    if TOKEN_FILE.exists():
        tokens = json.loads(TOKEN_FILE.read_text())
    tokens[service] = {
        "access_token": access_token,
        "refresh_token": refresh_token,
    }
    TOKEN_FILE.write_text(json.dumps(tokens))
    # Limita i permessi del file
    os.chmod(TOKEN_FILE, 0o600)

Il chmod a 0o600 non è decorativo: senza di esso, su una macchina condivisa, qualsiasi account può leggere i tuoi token. Il rinnovo, nel frattempo, si riduce a una chiamata POST all’token_url del servizio con il token di aggiornamento in mano. L’utente non vede passare nulla, ed è proprio questo il punto:

import httpx

async def refresh_access_token(
    token_url: str,
    client_id: str,
    client_secret: str,
    refresh_token: str,
) -> dict:
    """Rinnova il token di accesso tramite il token di aggiornamento."""
    async with httpx.AsyncClient() as http:
        response = await http.post(
            token_url,
            data={
                "grant_type": "refresh_token",
                "refresh_token": refresh_token,
                "client_id": client_id,
                "client_secret": client_secret,
            },
        )
        response.raise_for_status()
        return response.json()

Quando un token semplice è sufficiente

Non ogni server giustifica questo macchinario. Per uno strumento interno utilizzato da una manciata di sviluppatori, una chiave API passata in un header HTTP funziona perfettamente, e il client MCP la accetta direttamente:

from mistralai.extra.mcp.streamable_http import (
    MCPClientStreamableHTTP,
    StreamableHTTPServerParams,
)

# Server con token semplice
mcp_client = MCPClientStreamableHTTP(
    params=StreamableHTTPServerParams(
        url="https://my-server.com/mcp",
        headers={"Authorization": "Bearer my_secret_api_token"},
        timeout=60,
    )
)

Lato server, la verifica rientra in un middleware che intercetta le route pertinenti prima che raggiungano la tua logica di business:

from fastapi import FastAPI, Request, HTTPException

api = FastAPI()

@api.middleware("http")
async def verify_token(request: Request, call_next):
    if request.url.path.startswith("/mcp"):
        token = request.headers.get("Authorization", "")
        if token != "Bearer my_secret_api_token":
            raise HTTPException(status_code=401, detail="Unauthorized")
    return await call_next(request)

Cosa gestisce Vibe per te

In Vibe, i connettori in evidenza—GitHub, Gmail, Linear—hanno già OAuth configurato: l’utente clicca, concede il consenso ed è fatto. Per i tuoi connettori personalizzati, la configurazione offre le stesse tre opzioni descritte sopra: Nessuna autenticazione per un URL pubblico, Token se incolli la chiave a mano, e OAuth 2.0 per il flusso completo. Un dettaglio ha importanti conseguenze pratiche: il token è archiviato per utente, non per organizzazione. In un team Mistral, ogni membro passa quindi attraverso il proprio consenso e lavora con le proprie credenziali, il che impedisce che una partenza o una revoca blocchi l’accesso a tutti.

Punti chiave

  • OAuth 2.0 abilita il consenso esplicito con diritti limitati (scope)
  • Il flusso: autorizzazione → codice → token (accesso + aggiornamento)
  • Applica il principio del privilegio minimo agli scope
  • I token devono essere archiviati in modo sicuro e rinnovati automaticamente
  • Per casi semplici, un token statico negli header HTTP è sufficiente
  • In Vibe, i token sono archiviati per utente