Guide d'implémentation de l'authentification serveur MCP : utiliser la spécification la plus récente

Il y a quelques jours (18 juin 2025), l'équipe du MCP (Model Context Protocol) a publié la dernière version de la spécification MCP (2025-06-18). Cette mise à jour inclut un changement clé dans la spécification d'authentification. Les serveurs MCP n'émettront plus de jetons d'accès comme un Serveur d'Autorisation. À la place, ils consommeront des jetons d'accès et fourniront des ressources en tant que Serveur de Ressources.

En tant que l'un des mainteneurs de MCP Auth (une bibliothèque d'authentification plug-and-play pour serveur MCP), j'ai implémenté la prise en charge de la dernière spécification d'authentification MCP dans ce projet. Fort de mon expérience pratique, je vais te montrer comment implémenter les fonctionnalités d'authentification pour ton MCP Server conformément à la dernière spécification.

Cet article t'aidera à :

• Comprendre comment fonctionne l'authentification MCP avec la nouvelle spécification d'auth
• Clarifier ce que les serveurs MCP doivent implémenter en tant que serveurs de ressources selon la spécification d'auth MCP
• Fournir des conseils pour implémenter la prise en charge de l'auth qui respecte les exigences de la plus récente spécification d'auth MCP pour ton MCP Server
• Identifier les points oubliés et les problèmes de sécurité lors de la mise en œuvre de la spécification d'auth MCP

Remarque :

• Cet article suppose que les lecteurs ont des connaissances de base sur JWT (JSON Web Token). L'article ne couvrira pas en détail la structure, la vérification de signature et autres concepts fondamentaux. Pour plus de détails, consulte Auth Wiki - JWT
• Ne présente pas en détail les différentes RFC sur lesquelles s'appuie la spécification d'auth MCP. Il fournit seulement des implémentations conformes à ces RFC.
• Ne couvre pas les détails d'implémentation et d'interaction côté client MCP et autorisation. Ceux-ci sont généralement gérés par les clients LLM et les fournisseurs de serveurs d'autorisation qui prennent en charge MCP selon la spécification MCP. Les développeurs de serveurs MCP n'ont pas besoin, et ne peuvent pas, intervenir sur ces implémentations. Pour plus de détails, consulte OAuth Client et Authorization Server
• Tous les jetons d'accès mentionnés dans l'article sont supposés être des JWT, le format le plus utilisé sur le marché. D'autres formes de jetons doivent être utilisées selon la documentation fournie par le serveur d'autorisation correspondant.

Comment fonctionne l'auth MCP ?#

D'après la dernière spécification d'auth MCP, le flux d’auth MCP est illustré par le diagramme suivant :

1. Le client MCP demande une ressource au MCP Server à https://github-tools.com. Puisque l'utilisateur n'est pas encore connecté, l'en-tête d'autorisation HTTP de cette requête ne contient pas de jeton d'accès représentant l'utilisateur.

2. Le serveur MCP ne peut pas obtenir de jeton d'accès depuis l'en-tête d'autorisation de la requête du client MCP. Il renvoie une erreur HTTP 401 au client MCP. Cette réponse inclut un en-tête WWW-Authenticate, qui contient l'URL des métadonnées de ressource du serveur MCP (la valeur du champ resource_metadata).

3. Le client MCP extrait la valeur de resource_metadata depuis l'en-tête WWW-Authenticate retourné (par exemple : https://github-tools.com/.well-known/oauth-protected-resource). Ensuite, le client MCP demande les métadonnées de ressource fournies par le serveur MCP en tant que serveur de ressources à cette adresse. Ces métadonnées incluent des contenus comme authorization_servers et scopes_supported, pour aider le client MCP à savoir comment obtenir le jeton d'accès nécessaire pour accéder au serveur MCP, par exemple depuis quel serveur d'autorisation obtenir un jeton avec certains droits.

4-8. Le client MCP demande les métadonnées du serveur d'autorisation sur la base de l'URL obtenue dans les métadonnées de ressources. Puis il réalise un flux d'autorisation OAuth 2.1 avec le serveur d'autorisation et obtient un jeton d'accès après l'autorisation.

9. Le client MCP porte le jeton d'accès récupéré du serveur d'autorisation et effectue une nouvelle demande de ressource au serveur MCP.

10. Le serveur MCP renvoie la ressource demandée après vérification de la validité du jeton. Par la suite, la communication entre client MCP et serveur MCP continue avec ce jeton valide.

Ensuite, on va expliquer comment mettre en place, étape par étape, le mécanisme d'authentification du serveur MCP selon le workflow décrit précédemment.

Gérer les requêtes non autorisées : renvoyer une erreur 401 et l'en-tête WWW-Authenticate#

Comme montré dans le flux précédent, lorsqu'un client MCP envoie une requête sans jeton d'accès au serveur MCP, celui-ci renverra une erreur HTTP 401 Unauthorized avec un en-tête WWW-Authenticate contenant l'URL permettant d'obtenir les métadonnées de ressource du MCP Server.

Selon les exigences de gestion des erreurs de la spécification d'auth MCP, outre les requêtes sans jeton d’accès, le serveur MCP doit aussi répondre 401 avec un en-tête WWW-Authenticate lorsque le jeton reçu est invalide.

Après avoir identifié les cas nécessitant une erreur 401, comment construire l'en-tête WWW-Authenticate à retourner ?

Selon la RFC9728 Section 5.1, l'en-tête WWW-Authenticate doit inclure le paramètre resource_metadata qui indique l'URL des métadonnées de ressource protégée.

Son format de base est le suivant :

Ici, Bearer est le schéma d'authentification, indiquant qu'un jeton porteur est requis pour accéder à des ressources protégées OAuth 2.0 (voir : documentation MDN). La valeur du paramètre resource_metadata est l'URL complète de l'endpoint de métadonnées de ressource fourni par ton serveur MCP.

L’implémentation concrète du code ressemble à ceci :

Quand le Client MCP reçoit une telle erreur 401, il va accéder aux métadonnées de ressource du serveur MCP en utilisant la valeur de resource_metadata dans l'en-tête WWW-Authenticate. Ensuite, il utilisera les informations fournies par ces métadonnées pour déclencher une demande d’autorisation vers le serveur d’autorisation correspondant afin d’obtenir un jeton d’accès utilisable sur le serveur MCP.

Désormais tu sais quand retourner une erreur 401 et qu'il faut fournir l’URL des métadonnées de ressource. Mais il nous reste à voir comment construire cette URL et quel type de contenu doivent avoir ces métadonnées. C'est ce que nous allons voir ensuite.

Implémenter le mécanisme de découverte des métadonnées de ressource#

Selon le flux d’auth MCP, après réception d’un 401, le client MCP va immédiatement demander les métadonnées de ressource au serveur MCP. Le serveur MCP, en tant que Resource Server, doit donc fournir un mécanisme de découverte de ces métadonnées.

Déterminer le chemin de l’endpoint des métadonnées#

Dans le système OAuth, on utilise les URLs pour désigner les ressources. Cette adresse est appelée « indicateur de ressource » (resource indicator). D'après la RFC9728, les métadonnées doivent être hébergées sous un chemin /.well-known spécifique.

Si ton serveur MCP (par exemple https://github-tools.com) ne fournit qu’un seul service, l’endpoint sera :

Si tu fournis plusieurs services MCP différents sur un même hôte, chaque service doit avoir un endpoint de métadonnées distinct, par exemple la plateforme d’entreprise https://api.acme-corp.com propose :

• https://api.acme-corp.com/github - Service d’intégration GitHub
• https://api.acme-corp.com/slack - Service d’intégration Slack
• https://api.acme-corp.com/database - Service de requêtes base de données

Leurs endpoints de métadonnées respectifs sont :

• 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

L'avantage de ce design est que chaque service peut avoir des scopes de permissions et des serveurs d'autorisation différents. Par exemple :

• Le service GitHub utilise un serveur OAuth GitHub, nécessite les permissions github:read, github:write
• Le service Slack s'appuie sur le serveur Slack OAuth, nécessite slack:channels:read, slack:messages:write
• Le service Database dépend d'un serveur d’autorisation interne, et nécessite db:query

On peut résumer l’URL de l’endpoint des métadonnées ainsi :

On obtient ainsi l’URL d’endpoint de la ressource à partir de l’indicateur de ressource :

Construire la réponse de métadonnées de ressource#

Après avoir déterminé le chemin de l’endpoint, il faut que cette URL réponde en JSON selon RFC9728.

En pratique, il faut se concentrer sur quatre champs principaux.

Le premier est le champ resource qui est l’identifiant de la ressource, et qui doit correspondre à l’URL que veut atteindre le client MCP.

Ensuite, le champ authorization_servers est un tableau qui liste les serveurs d’autorisation depuis lesquels le client MCP doit demander ses jetons d’accès. Selon OAuth 2.0 Protected Resource Metadata (RFC 9728), ce champ est optionnel, mais selon la spécification MCP, il est requis : le client MCP doit connaître explicitement vers quel serveur d’autorisation se tourner pour l’obtention de jeton; sans cela, il ne peut finaliser le flux OAuth.

Puis, le champ scopes_supported qui liste l’ensemble des scopes supportés par ce serveur de ressources.

Enfin, le champ bearer_methods_supported qui indique par quel moyen le serveur MCP attend de recevoir le jeton d’accès. En général, on met ["header"], ce qui signifie que le client MCP doit transmettre le jeton dans l’en-tête HTTP Authorization.

Voici un exemple concret pour le serveur MCP https://github-tools.com :

Cette configuration informe le client MCP des points suivants : il souhaite accéder à https://github-tools.com, il doit demander le jeton d’accès auprès de https://auth.github-tools.com, il peut demander les permissions github:read, github:write, repo:admin, et devra fournir le token via l’en-tête HTTP Authorization.

Pour la plupart des cas, ces quatre champs de base suffisent à faire fonctionner le client MCP. Pour des besoins plus complexes, se référer à la RFC9728 pour consulter la liste complète des champs possibles.

Valider les jetons d'accès#

Après que le client MCP ait obtenu un jeton d’accès du serveur d’autorisation, il le fournira au serveur MCP lors de sa demande de ressource.

En pratique, un serveur MCP doit respecter les points suivants lors de la validation du jeton d’accès :

1. Lors de la validation de base, utiliser la configuration du serveur MCP, pas les informations du serveur d’autorisation présentes dans le jeton.
2. Vérifier que l'audience du token correspond bien au serveur MCP (qu’il a été délivré pour accéder aux ressources de ce serveur).
3. Bien gérer la validation des scopes.

Utiliser la configuration du serveur MCP pour valider les jetons d’accès#

Quand le serveur MCP reçoit un jeton d’accès, comme ce jeton porte en soi l’information du serveur d’autorisation (issuer), certains développeurs récupèrent directement ces infos pour valider le jeton. C’est particulièrement le cas si la ressource MCP expose plusieurs serveurs d’autorisation, exemple :

Dans ce cas, certains extrairont le issuer du token non vérifié pour choisir le serveur sur lequel valider celui-ci. Des attaquants pourraient fabriquer un serveur d’autorisation malicieux qui émet un faux jeton d’accès ciblant le serveur MCP. Si le développeur se fie à cet issuer malicieux, la validation risque de « réussir ».

La bonne procédure :

• Si un seul serveur d’autorisation est configuré : valider le token selon le serveur configuré en backend.
• Si plusieurs serveurs d’autorisation sont listés : extraire l’issuer depuis le token non vérifié, chercher s’il existe dans la configuration locale, puis valider uniquement s’il y a correspondance. Sinon, rejeter le token.

Bien entendu, il faut valider strictement la propriété issuer.

Avec la librairie jose :

Validation de l’audience du jeton#

La section sur la validation de l’audience de la spécification MCC précise que lorsqu’un client demande un jeton au serveur d’autorisation, il doit indiquer à quelle ressource ce jeton servira. Le serveur MCP doit vérifier que la propriété audience du token correspond bien à sa propre identité.

Il s’appuie ici sur les Resource Indicators for OAuth 2.0 (RFC 8707). Le workflow :

1. Phase requête côté client : le client MCP fournit le paramètre resource à l’autorisation, indiquant à quelle ressource il veut accéder (ex : https://github-tools.com).

2. Phase émission du token : le serveur d’autorisation lie cette ressource demandée au jeton d’accès via le champ audience (abrégé aud) dans le JWT.

3. Phase validation : à réception du jeton, le serveur MCP vérifie que le champ d’audience (aud) soit strictement égal à son identifiant de ressource.

Exemple :

Cette validation d’audience est un verrou clé de sécurité pour éviter l’abus de jetons. Sans elle, des utilisateurs malicieux pourraient faire passer des jetons prévus pour d’autres services afin d’accéder à ton serveur MCP.

Validation des scopes#

Certains serveurs MCP gèrent des autorisations d’accès différenciées selon l’utilisateur.

Après la validation du token, il faut donc encore vérifier que les scopes nécessaires sont bien présents dans le token :

Selon la spécification d'auth MCP, si le token ne couvre pas le scope requis, il faut répondre 403 Forbidden.

Conclusion#

Grâce à cet article, tu devrais être capable d’implémenter un mécanisme d’authentification conforme à la dernière version de la spécification MCP pour ton serveur. Retiens bien : vérifie soigneusement les tokens, configure métadonnées et audience strictement.

Si tu construis un serveur MCP, essaie la bibliothèque MCP Auth. Elle implémente déjà toutes les fonctionnalités décrites ci-dessus et permet une intégration rapide de l’authentification.

N’hésite pas à discuter sur GitHub. Construisons ensemble l’écosystème MCP !