Guida all'implementazione dell'autenticazione server MCP: utilizzo dell'ultima specifica

Qualche giorno fa (18 giugno 2025), il team MCP (Model Context Protocol) ha rilasciato l'ultima versione della Specifica MCP (2025-06-18). Questo aggiornamento include una modifica fondamentale alla specifica di autenticazione. I server MCP non rilasceranno più access token come un Authorization Server. Invece, consumeranno gli access token e forniranno le risorse come un Resource Server.

Come uno dei manutentori di MCP Auth (una libreria plug-and-play per l'autenticazione server MCP), ho implementato il supporto all'ultima specifica di autenticazione MCP in questo progetto. Basandomi sulla mia esperienza pratica, ti mostrerò come implementare funzionalità di autenticazione per il tuo server MCP in conformità con la nuova specifica.

Questo articolo ti aiuterà a:

• Comprendere come funziona l'autenticazione MCP secondo la nuova specifica
• Chiarire cosa devono implementare i server MCP come Resource Server secondo i requisiti della specifica di autenticazione MCP
• Fornire linee guida per implementare il supporto auth che risponde ai requisiti più recenti per il tuo server MCP
• Identificare punti trascurati e problemi di sicurezza nell'implementazione della specifica auth MCP

Nota che questo articolo:

• Presuppone che i lettori abbiano conoscenze di base sui JWT (JSON Web Token). L'articolo non tratterà nel dettaglio la struttura dei JWT, la verifica della firma e altri concetti fondamentali. Per dettagli specifici, consulta Auth Wiki - JWT
• Non introduce in modo approfondito le varie RFC su cui si basa la specifica auth MCP. Si limita a fornire implementazioni conformi a tali RFC
• Non tratta i dettagli di implementazione e interazione di Client MCP e Authorization. Questi sono solitamente realizzati dai client LLM e dai provider di server di autorizzazione che supportano MCP in base alle specifiche MCP. Gli sviluppatori MCP Server non devono e non possono intervenire sulle implementazioni correlate. Per dettagli specifici, consulta OAuth Client e Authorization Server
• Tutti gli access token menzionati nell'articolo sono considerati JWT, che è il formato più diffuso sul mercato. Altri formati di token devono essere utilizzati secondo la documentazione fornita dal relativo fornitore di server di autorizzazione.

Come funziona l'autenticazione MCP?#

Secondo la più recente specifica auth MCP, il flusso di autenticazione MCP è illustrato nel seguente diagramma:

1. Il client MCP richiede risorse dal server MCP su https://github-tools.com. Poiché l'utente non ha ancora effettuato il login, l'header HTTP di autorizzazione della richiesta non contiene un access token che rappresenta l'utente.

2. Il server MCP non può ottenere un access token dall'header di autorizzazione della richiesta del client MCP. Restituisce un errore HTTP 401 al client MCP. Questa risposta di errore include un header WWW-Authenticate, che contiene l'URL dei metadati della risorsa del server MCP (il valore del campo resource_metadata).

3. Il client MCP estrae il valore di resource_metadata dall'header WWW-Authenticate restituito (ad esempio: https://github-tools.com/.well-known/oauth-protected-resource). Quindi il client MCP richiede i metadati della risorsa forniti dal server MCP come Resource Server da questo indirizzo. Questi metadati includono contenuti come authorization_servers e scopes_supported, aiutando il client MCP a capire come ottenere l'access token necessario per accedere al server MCP, ad esempio da quale authorization server ottenere un token con determinati permessi.

4-8. Il client MCP richiede informazioni sui metadati del server di autorizzazione basandosi sull'URL dei metadati ricevuto dai metadati della risorsa. Successivamente, il client MCP esegue il flusso di autorizzazione OAuth 2.1 con il server di autorizzazione e, una volta autorizzato, ottiene un access token.

9. Il client MCP porta l'access token ottenuto dal server di autorizzazione ed effettua una nuova richiesta di risorsa al server MCP.

10. Dopo aver verificato che il token sia valido, il server MCP restituisce la risorsa richiesta. Da quel momento, la comunicazione tra client MCP e server MCP continuerà con il token valido.

Successivamente spiegheremo come implementare il meccanismo di autenticazione del server MCP passo dopo passo in base al flusso di lavoro presentato.

Gestire le richieste non autorizzate: restituzione errore 401 ed header WWW-Authenticate#

Come mostrato nel flusso sopra, quando il client MCP invia una richiesta senza access token al server MCP, il server MCP restituisce un errore HTTP 401 Unauthorized con un header WWW-Authenticate che include l'URL per ottenere i metadati della risorsa del server MCP.

Secondo i requisiti di gestione degli errori della specifica MCP auth, oltre ai casi in cui le richieste dei client MCP non portano access token, quando il server MCP riceve un access token non valido deve restituire anch'esso un errore 401 con un header WWW-Authenticate.

Dopo aver chiarito quando restituire l'errore 401, come si costruisce l'header WWW-Authenticate restituito?

Secondo RFC9728 Sezione 5.1, l'header WWW-Authenticate deve includere un parametro resource_metadata per indicare l'URL dei metadati della risorsa protetta.

Il suo formato base è il seguente:

Qui, Bearer è lo schema di autenticazione e indica che è necessario un bearer token per accedere a risorse protette da OAuth 2.0 (vedi: MDN documentation). Il valore del parametro resource_metadata deve essere l'URL completo dell'endpoint metadati fornito dal tuo server MCP.

L'implementazione reale in codice è simile a questa:

Quando il client MCP riceve tale errore 401, accederà ai metadati della risorsa tramite il valore di resource_metadata nell'header WWW-Authenticate. Poi, in base alle informazioni fornite dai metadati della risorsa, avvierà una richiesta di autorizzazione al server di autorizzazione specificato per ottenere un access token utilizzabile per accedere al server MCP.

Ora sappiamo quando restituire un errore 401 e che dobbiamo includere un URL resource_metadata. Ma non sappiamo ancora come costruire questo URL e cosa devono contenere i metadati. Lo spiegheremo di seguito.

Implementare il meccanismo di discovery dei metadati della risorsa#

Secondo il flusso auth MCP, dopo aver ricevuto un errore 401 il client MCP richiede subito i metadati della risorsa dal server MCP. Perciò il server MCP, come Resource Server, deve implementare un meccanismo di discovery dei metadati della risorsa.

Determinare il percorso URL dell'endpoint dei metadati#

Nel sistema OAuth, vengono usati gli URL come indicatori delle risorse ("resource indicator"). Secondo RFC9728, i metadati della risorsa devono essere ospitati sotto un percorso specifico /.well-known.

Se il tuo server MCP (come https://github-tools.com) fornisce un solo servizio, l'endpoint dei metadati deve essere:

Se invece offri più servizi MCP su uno stesso host, ogni servizio deve avere un endpoint metadati indipendente. Per esempio, la piattaforma enterprise https://api.acme-corp.com offre i seguenti servizi:

• https://api.acme-corp.com/github - Integrazione GitHub
• https://api.acme-corp.com/slack - Integrazione Slack
• https://api.acme-corp.com/database - Servizio query database

Gli endpoint metadati corrispondenti saranno:

• https://api.acme-corp.com/.well-known/oauth-protected-resource/github
• https://api.acme-corp.com/.well-known/oauth-protected-resource/slack
• https://api.acme-corp.com/.well-known/oauth-protected-resource/database

Il vantaggio di questa progettazione è che ogni servizio può avere ambiti di permessi e configurazioni di authorization server diversi. Ad esempio:

• Il servizio GitHub usa il server OAuth di GitHub e richiede i permessi github:read, github:write
• Il servizio Slack usa il server OAuth di Slack e richiede slack:channels:read, slack:messages:write
• Il servizio Database usa il server di autorizzazione interno aziendale e richiede il permesso db:query

In base a questi casi, si può riassumere che gli endpoint seguono questo pattern:

Possiamo ricavare l'endpoint metadati in questo modo:

Costruire la risposta dei metadati della risorsa#

Dopo aver definito il path dell'endpoint, bisogna far sì che questo endpoint restituisca metadati in formato JSON conformi alla RFC9728.

In pratica, bisogna concentrarsi su quattro campi chiave.

Il primo è il campo resource, ovvero l'identificatore della risorsa, che deve coincidere con l'indirizzo della risorsa richiesta dal client MCP.

Poi c'è authorization_servers, un array che specifica da quali authorization server il client MCP deve ottenere gli access token. Secondo la RFC 9728 questo campo è opzionale, ma nella specifica MCP auth è obbligatorio perché il client MCP deve sapere chiaramente a quale authorization server inviare la richiesta. Senza questa informazione non può completare il flusso OAuth.

C'è poi scopes_supported, che elenca tutti gli ambiti supportati dal Resource Server.

Infine, il campo bearer_methods_supported, che indica al client MCP quali metodi sono supportati dal server per ricevere gli access token. Di solito si imposta ["header"] indicando che, dopo aver ottenuto il token dal server di autorizzazione, il client MCP deve inviarlo nell'header HTTP Authorization.

Esempio pratico: configurazione dei metadati per il server MCP https://github-tools.com:

Questa configurazione comunica al client MCP: vuole accedere alla risorsa https://github-tools.com, deve ottenere l'access token da https://auth.github-tools.com, può richiedere i permessi github:read, github:write, repo:admin e deve trasmettere il token tramite l'header HTTP Authorization.

Per la maggior parte degli scenari, configurare questi quattro campi fondamentali è sufficiente per il funzionamento corretto del client MCP. Se serve una configurazione più complessa, consulta l'elenco completo dei campi in RFC9728.

Validare gli access token#

Dopo che il client MCP ha ottenuto l'access token dal server di autorizzazione, porterà questo token per accedere al server MCP.

Nella pratica, i server MCP devono prestare attenzione a questi punti durante la validazione:

1. Al momento della validazione di base del token, usare la configurazione del server MCP, non prendere i dati dal token stesso per recuperare info sull'authorization server.
2. Validare che l'audience del token sia il server MCP, per garantire che il token sia stato effettivamente emesso per l'accesso alle sue risorse.
3. Gestire correttamente la validazione degli scope

Usare la configurazione del server MCP per validare gli access token#

Quando il server MCP riceve un access token, poiché questo token contiene info sull'authorization server (issuer), alcuni sviluppatori prendono direttamente l'issuer dal token non verificato e recuperano i dati del server di autorizzazione da ciò che è riportato nel token. Questo avviene soprattutto quando i metadati della risorsa MCP restituiscono più server di autorizzazione, come nell'esempio:

In questa situazione, molti sviluppatori estraggono l'issuer direttamente dal token non verificato per poi abbinare l'issuer ai dati di validazione. Un attaccante potrebbe però costruire un authorization server maligno, rilasciare un fake access token per il server MCP e se lo sviluppatore si fida dell'issuer estratto dal fake token per la validazione, finirà per accettare l'access token falso.

Il metodo corretto è:

• Quando è configurato un solo authorization server: validare il token direttamente usando i dati di backend di quell'authorization server
• Quando sono configurati più authorization server: estrarre l'issuer dal token non verificato e cercare solo nei server di autorizzazione configurati localmente; se nessuno corrisponde, rifiutare il token

Ovviamente, durante la validazione, bisogna validare in modo rigoroso l'issuer del token.

Esempio con la libreria jose JWT:

Validare l'audience del token#

La sezione Token Audience Binding and Validation della specifica MCP auth afferma che quando un client richiede un access token a un authorization server, deve specificare quale resource server (risorsa) viene richiesta. Anche il server MCP, durante la validazione del token, deve controllare che l'audience del token sia il suo proprio identificatore di risorsa.

Questo meccanismo si basa sulla Resource Indicators for OAuth 2.0 (RFC 8707). In sintesi, il workflow è:

1. Fase di richiesta client: il client MCP chiede un access token all'authorization server, specificando il parametro resource che indica a quale server verrà usato il token (es. https://github-tools.com)

2. Fase di emissione: dopo aver ricevuto la richiesta, il server di autorizzazione lega l'indirizzo della risorsa al token. Per i JWT, l'indirizzo va nel payload come valore del campo audience (aud)

3. Fase di validazione: il server MCP alla ricezione del token deve controllare che il campo audience del JWT corrisponda al proprio identificatore

Usando come esempio MCP Server https://github-tools.com:

Questa validazione dell'audience è un meccanismo di sicurezza fondamentale contro l'abuso dei token. Senza questa validazione, un attaccante potrebbe usare access token rilasciati per altri servizi e tentare di accedere al tuo server MCP. Se non validi l'audience, potresti accettare token non destinati al tuo servizio.

Validazione degli scope#

Alcuni server MCP gestiscono permessi di accesso alle risorse interne perché utenti diversi possono avere scope diversi.

Quindi, una volta che l'access token ha superato la validazione, serve controllare se include i permessi richiesti dall'operazione. Basta verificare che il claim scope nel token includa le autorizzazioni richieste:

Ricorda che secondo la specifica MCP auth, se il token non ha lo scope richiesto dalla risorsa richiesta, va restituito errore 403 Forbidden.

Conclusione#

Attraverso questa guida dovresti essere in grado di implementare la funzionalità di autenticazione conforme all'ultima specifica per il tuo server MCP. Ricorda alcuni punti chiave: valida i token in modo sicuro, configura correttamente i metadati, verifica rigorosamente l'audience.

Se stai costruendo un server MCP, prova la libreria MCP Auth. Ha già implementato tutte le funzionalità descritte in questo articolo e può aiutarti a integrare velocemente il supporto auth.

Sentiti libero di discutere eventuali dubbi su GitHub. Lavoriamo insieme per far crescere l'ecosistema MCP.