Configurer MCP Auth sur le serveur MCP

Avec la dernière Spécification MCP (2025-06-18), votre serveur MCP agit comme un Serveur de ressources qui valide les jetons d’accès (Access tokens) émis par des serveurs d’autorisation externes.

Pour configurer MCP Auth, deux étapes principales sont nécessaires :

1. Configurer les métadonnées du serveur d’autorisation — Définir quels serveurs d’autorisation peuvent émettre des jetons valides pour votre serveur MCP et indiquer aux clients MCP où obtenir les jetons d’accès (Access tokens)
2. Configurer les métadonnées de la ressource protégée — Définir votre serveur MCP comme une ressource protégée avec les portées (Scopes) prises en charge

Étape 1 : Configurer les métadonnées du serveur d’autorisation

Récupération automatique des métadonnées

La façon la plus simple de configurer les métadonnées du serveur d’autorisation est d’utiliser les fonctions intégrées qui récupèrent les métadonnées depuis les URLs bien connues. Si votre fournisseur est conforme à l’une des normes suivantes :

• OAuth 2.0 Authorization Server Metadata
• OpenID Connect Discovery

Vous pouvez utiliser fetchServerConfig pour récupérer automatiquement les métadonnées en fournissant l’URL de l’issuer :

import { fetchServerConfig } from 'mcp-auth';

// Récupérer les métadonnées du serveur d’autorisation
const authServerConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' }); // ou 'oauth'

Si votre issuer inclut un chemin, le comportement diffère légèrement entre OAuth 2.0 et OpenID Connect :

• OAuth 2.0 : L’URL bien connue est ajoutée au domaine de l’issuer. Par exemple, si votre issuer est https://my-project.logto.app/oauth, l’URL bien connue sera https://auth.logto.io/.well-known/oauth-authorization-server/oauth.
• OpenID Connect : L’URL bien connue est ajoutée directement à l’issuer. Par exemple, si votre issuer est https://my-project.logto.app/oidc, l’URL bien connue sera https://auth.logto.io/oidc/.well-known/openid-configuration.

Découverte à la demande

Si vous utilisez des environnements edge comme Cloudflare Workers où le fetch asynchrone au niveau supérieur n’est pas autorisé, vous pouvez utiliser la découverte à la demande. Il suffit de fournir l’issuer et le type, et les métadonnées seront récupérées automatiquement lors du premier besoin :

const authServerConfig = { issuer: '<issuer-url>', type: 'oidc' }; // ou 'oauth'

Autres méthodes pour configurer les métadonnées du serveur d’autorisation

Transpilation personnalisée des données

Dans certains cas, les métadonnées retournées par le fournisseur peuvent ne pas être conformes au format attendu. Si vous êtes certain que le fournisseur est conforme, vous pouvez utiliser l’option transpileData pour modifier les métadonnées avant leur utilisation :

import { fetchServerConfig } from 'mcp-auth';

const authServerConfig = await fetchServerConfig('<auth-server-issuer>', {
  type: 'oidc',
  transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), 
});

Cela vous permet de modifier l’objet de métadonnées avant qu’il ne soit utilisé par MCP Auth. Par exemple, vous pouvez ajouter ou supprimer des champs, modifier leurs valeurs ou les convertir dans un autre format.

Récupérer les métadonnées depuis une URL spécifique

Si votre fournisseur dispose d’une URL de métadonnées spécifique plutôt que des URLs standard, vous pouvez l’utiliser de manière similaire :

import { fetchServerConfigByWellKnownUrl } from 'mcp-auth';

const authServerConfig = await fetchServerConfigByWellKnownUrl('<metadata-url>', { type: 'oidc' }); // ou 'oauth'

Récupérer les métadonnées depuis une URL spécifique avec transpilation personnalisée

Dans certains cas, la réponse du fournisseur peut être mal formée ou non conforme au format de métadonnées attendu. Si vous êtes certain que le fournisseur est conforme, vous pouvez transpiler les métadonnées via l’option de configuration :

const authServerConfig = await fetchServerConfigByWellKnownUrl('<metadata-url>', {
  type: 'oidc',
  transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), 
});

Fournir manuellement les métadonnées

Si votre fournisseur ne prend pas en charge la récupération des métadonnées, vous pouvez fournir manuellement l’objet de métadonnées :

const authServerConfig = {
  metadata: {
    issuer: '<issuer-url>',
    // Les champs de métadonnées doivent être en camelCase
    authorizationEndpoint: '<authorization-endpoint-url>',
    // ... autres champs de métadonnées
  },
  type: 'oidc', // ou 'oauth'
};

Étape 2 : Configurer les métadonnées de la ressource protégée

Après avoir configuré les métadonnées du serveur d’autorisation, vous devez initialiser MCPAuth en tant que Serveur de ressources en définissant les métadonnées de vos ressources protégées.

Cette étape suit la spécification RFC 9728 (OAuth 2.0 Protected Resource Metadata) pour décrire votre serveur MCP comme une ressource protégée :

import { MCPAuth } from 'mcp-auth';

// Définir l’identifiant de votre ressource
const resourceIdentifier = 'https://api.example.com/notes';

// Initialiser MCPAuth en mode serveur de ressources
const mcpAuth = new MCPAuth({
  protectedResources: {
    metadata: {
      resource: resourceIdentifier,
      authorizationServers: [authServerConfig], // Utilisation de la config de l’étape 1
      scopesSupported: ['read:notes', 'write:notes'],
    },
  },
});

Pour plusieurs ressources, vous pouvez fournir un tableau de configurations de ressources protégées, chacune avec sa propre configuration de métadonnées.

La configuration ci-dessus couvre la configuration de base. Pour des paramètres de métadonnées plus avancés, voir RFC 9728.

Étape 3 : Monter l’endpoint des métadonnées de la ressource protégée

Montez le routeur pour servir l’endpoint des métadonnées de la ressource protégée. Le chemin de l’endpoint est automatiquement déterminé par le composant chemin de votre identifiant de ressource :

• Sans chemin : https://api.example.com → /.well-known/oauth-protected-resource
• Avec chemin : https://api.example.com/notes → /.well-known/oauth-protected-resource/notes

import express from 'express';

const app = express();

const mcpAuth = new MCPAuth({/* ... */});

app.use(mcpAuth.protectedResourceMetadataRouter());