AI & MCP
OAuth per server MCP: il flusso, i controlli e cosa resta al client
Un server MCP remoto usa OAuth 2.1: 401, metadata, consenso, token opaco. Ecco i sei endpoint, i controlli obbligatori e il limite del nostro server.
In sintesi
- La specifica 2025-06-18 richiede OAuth 2.1, RFC 9728, RFC 8414 e il parametro resource di RFC 8707.
- Il server risponde 401 con WWW-Authenticate e lascia al client la scoperta dei metadata.
- PKCE S256, redirect_uri esatto e refresh a rotazione sono i tre controlli che fermano un token rubato.
Un server MCP remoto autentica il client con OAuth 2.1, in sei endpoint, e non chiede mai una password al client. Il flusso è quello del resource server: 401, metadata, consenso, token opaco legato a un solo resource.
Cosa chiede la specifica
La revisione 2025-06-18 parte da OAuth 2.1 (draft -13) e ne impone un sottoinsieme. Il server MCP deve pubblicare i Protected Resource Metadata di RFC 9728, l'authorization server deve pubblicare i metadata di RFC 8414, e il client deve mandare il parametro resource di RFC 8707 sia nella richiesta di autorizzazione sia in quella del token. PKCE è obbligatorio e il redirect_uri deve combaciare con un valore registrato, non con un prefisso.
Il flusso in cinque passi
- Il client chiama
/mcpsenza token e riceve 401 con l'headerWWW-Authenticateche punta al resource metadata. - Legge
/.well-known/oauth-protected-resourcee trova l'authorization server. - Legge
/.well-known/oauth-authorization-servere, se serve, registra il client conPOST /oauth/register. - Apre il browser su
/oauth/authorizeconcode_challengeeresource; l'utente approva e torna al client con?code=. - Scambia il code su
/oauth/tokenconcode_verifiere riceve access token e refresh token.
Registrare il client
curl -s -X POST https://ui.eneawork.it/oauth/register \
-H "Content-Type: application/json" \
-d '{"client_name":"Claude Code","redirect_uris":["http://localhost:3000/callback"]}'La risposta contiene client_id e token_endpoint_auth_method: none. Non c'è un client secret, ed è una scelta: un client MCP è un editor o un'app desktop, e un segreto dentro un binario si legge con strings. La registrazione dinamica di RFC 7591 resta raccomandata, non obbligatoria: un server senza di essa deve dare un client id per un'altra via.
I sei endpoint
| Endpoint | Metodo | Cosa restituisce |
|---|---|---|
| /.well-known/oauth-protected-resource | GET | resource, authorization_servers, scopes_supported |
| /.well-known/oauth-authorization-server | GET | issuer, authorization_endpoint, token_endpoint, registration_endpoint |
| /oauth/register | POST | client_id pubblico e redirect_uris registrati |
| /oauth/authorize | GET, POST | pagina di consenso, poi redirect con ?code= |
| /oauth/token | POST | access_token, refresh_token, expires_in |
| /mcp | POST | 401 con WWW-Authenticate finché manca un token valido |
Il confine del nostro server
Il token è opaco e salvato come SHA-256, poi risolto a un account. Non porta il claim di audience di RFC 8707: con un solo resource pubblico la differenza è nulla, con due resource servirebbe il controllo di audience. Anche lo scope è uno, mcp: non c'è un modo per concedere la lettura del catalogo e negare il comando di installazione.
La limitazione
Il flusso protegge il trasporto, non il contenuto. Un tool può restituire testo che contiene istruzioni, e un client che le esegue trasforma il risultato in prompt injection. La specifica lo dice: i risultati restano dati non fidati, e il consenso dell'utente non li rende sicuri.
Dove continuare
La costruzione del server è in costruire un server MCP, il disegno degli strumenti in progettare un tool MCP. Per il lato client leggi sicurezza di un agente di coding, e per gli schermi di login reali la rassegna blocchi di autenticazione. Il catalogo dietro il token è in 111.985 componenti e 1.556 blocchi; un record con licenza non dichiarata a monte è login form di minhxthanh.
Domande frequenti
Serve OAuth per un server MCP locale?
No. La specifica dice che un server stdio non deve usare il flusso OAuth e deve leggere le credenziali dall'ambiente. OAuth serve al trasporto HTTP, dove il client è remoto.
Perché il code dura solo 60 secondi?
Perché un code intercettato vale un token. Sessanta secondi bastano al browser per tornare al client e rendono inutile un code copiato da un log. Il valore è in backend/mcp-oauth.js, verificato il 1 novembre 2026.
Cosa succede se un refresh token viene rubato?
Il refresh ruota a ogni uso e la riga vecchia viene cancellata. Il primo dei due che lo usa vince, il secondo riceve invalid_grant. L'utente vede la connessione rotta e revoca il client dalla pagina account.
Il client deve mandare il token a ogni richiesta?
Sì. OAuth 2.1 lo richiede a ogni richiesta HTTP, anche dentro la stessa sessione MCP. Il token non va mai messo nella query string, perché finirebbe nei log del proxy.
Quanti scope espone il vostro server?
Uno, mcp. Copre la ricerca, la lettura dei metadata e i comandi di installazione consentiti dal piano. Non c'è uno scope separato per la scrittura perché il server è in sola lettura.