Configurer MCP Auth sur le serveur MCP

Avec la dernière Spécification MCP (2025-06-18), votre serveur MCP agit en tant que 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 :

Python

from mcpauth.config import AuthServerType
from mcpauth.utils import fetch_server_config

# Récupérer les métadonnées du serveur d’autorisation
auth_server_config = fetch_server_config(
    "https://auth.logto.io/oidc",
    AuthServerType.OIDC  # ou AuthServerType.OAUTH
)

Node.js

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.

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 transpile_data pour modifier les métadonnées avant leur utilisation :

Python

from mcpauth.config import AuthServerType
from mcpauth.utils import fetch_server_config

auth_server_config = fetch_server_config(
    '<auth-server-url>',
    type=AuthServerType.OIDC,
    transpile_data=lambda data: {**data, 'response_types_supported': ['code']} 
)

Node.js

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 son utilisation 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 :

Python

from mcpauth.config import AuthServerType
from mcpauth.utils import fetch_server_config_by_well_known_url

auth_server_config = fetch_server_config_by_well_known_url(
    '<metadata-url>',
    type=AuthServerType.OIDC # ou AuthServerType.OAUTH
)

Node.js

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 attendu. Si vous êtes certain que le fournisseur est conforme, vous pouvez transpiler les métadonnées via l’option de configuration :

Python

from mcpauth.config import AuthServerType, fetch_server_config_by_well_known_url

auth_server_config = fetch_server_config_by_well_known_url(
    '<metadata-url>',
    type=AuthServerType.OIDC,
    transpile_data=lambda data: {**data, 'response_types_supported': ['code']} 
)

Node.js

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 :

Python

from mcpauth.config import AuthServerConfig, AuthServerType, AuthorizationServerMetadata

auth_server_config = AuthServerConfig(
    type=AuthServerType.OIDC,  # ou AuthServerType.OAUTH
    metadata=AuthorizationServerMetadata(
        issuer='<issuer-url>',
        authorization_endpoint='<authorization-endpoint-url>',
        # ... autres champs de métadonnées
    ),
)

Node.js

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 :

Python

from mcpauth import MCPAuth
from mcpauth.config import ResourceServerConfig, ResourceServerMetadata

# Définir l’identifiant de votre ressource
resource_id = "https://api.example.com/notes"

# Initialiser MCPAuth en mode serveur de ressources
mcp_auth = MCPAuth(
    protected_resources=ResourceServerConfig(
        metadata=ResourceServerMetadata(
            resource=resource_id,
            authorization_servers=[auth_server_config],  # Utilisation de la config de l’étape 1
            scopes_supported=[
                "read:notes",
                "write:notes",
            ],
        )
    )
)

Node.js

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 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 le point de terminaison des métadonnées de la ressource protégée

Montez le routeur pour servir le point de terminaison des métadonnées de la ressource protégée. Le chemin du point de terminaison 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

Python

from starlette.applications import Starlette
from mcpauth import MCPAuth

mcp_auth = MCPAuth({/* ... */})

app = Starlette(routes=[
    *mcp_auth.resource_metadata_router().routes,
])

Node.js

import express from 'express';

const app = express();

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

app.use(mcpAuth.protectedResourceMetadataRouter());