Saltar al contenido principal

Configura MCP Auth en el servidor MCP

Con la última Especificación MCP (2025-06-18), tu servidor MCP actúa como un Servidor de Recursos (Resource Server) que valida los tokens de acceso emitidos por servidores de autorización externos.

Para configurar MCP Auth, necesitas dos pasos principales:

  1. Configurar los metadatos del servidor de autorización (Authorization Server Metadata) - Define qué servidores de autorización pueden emitir tokens válidos para tu servidor MCP y guía a los clientes MCP sobre dónde obtener tokens de acceso.
  2. Configurar los metadatos del recurso protegido (Protected Resource Metadata) - Define tu servidor MCP como un recurso protegido con los alcances (scopes) soportados.

Paso 1: Configura los metadatos del servidor de autorización​

Obtención automática de metadatos​

La forma más sencilla de configurar los metadatos del servidor de autorización es utilizando las funciones integradas que obtienen los metadatos desde URLs bien conocidas. Si tu proveedor cumple con uno de los siguientes estándares:

Puedes usar fetchServerConfig para recuperar automáticamente los metadatos proporcionando la URL del issuer:

import { fetchServerConfig } from 'mcp-auth';

// Obtener metadatos del servidor de autorización
const authServerConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' }); // o 'oauth'

Si tu issuer incluye una ruta, el comportamiento difiere ligeramente entre OAuth 2.0 y OpenID Connect:

  • OAuth 2.0: La URL bien conocida se añade al dominio del issuer. Por ejemplo, si tu issuer es https://my-project.logto.app/oauth, la URL bien conocida será https://auth.logto.io/.well-known/oauth-authorization-server/oauth.
  • OpenID Connect: La URL bien conocida se añade directamente al issuer. Por ejemplo, si tu issuer es https://my-project.logto.app/oidc, la URL bien conocida será https://auth.logto.io/oidc/.well-known/openid-configuration.

Descubrimiento bajo demanda​

Si utilizas entornos edge como Cloudflare Workers donde no se permite el fetch asíncrono a nivel superior, puedes usar el descubrimiento bajo demanda. Solo proporciona el issuer y el type, y los metadatos se obtendrán automáticamente cuando se necesiten por primera vez:

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

Otras formas de configurar los metadatos del servidor de autorización​

Transpilación personalizada de datos​

En algunos casos, los metadatos devueltos por el proveedor pueden no ajustarse al formato esperado. Si estás seguro de que el proveedor es compatible, puedes usar la opción transpileData para modificar los metadatos antes de que se utilicen:

import { fetchServerConfig } from 'mcp-auth';

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

Esto te permite modificar el objeto de metadatos antes de que lo use MCP Auth. Por ejemplo, puedes añadir o eliminar campos, cambiar sus valores o convertirlos a un formato diferente.

Obtener metadatos desde una URL específica​

Si tu proveedor tiene una URL de metadatos específica en lugar de las estándar, puedes usarla de manera similar:

import { fetchServerConfigByWellKnownUrl } from 'mcp-auth';

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

Obtener metadatos desde una URL específica con transpilación personalizada de datos​

En algunos casos, la respuesta del proveedor puede estar malformada o no ajustarse al formato de metadatos esperado. Si estás seguro de que el proveedor es compatible, puedes transpilar los metadatos mediante la opción de configuración:

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

Proporcionar manualmente los metadatos​

Si tu proveedor no admite la obtención de metadatos, puedes proporcionar manualmente el objeto de metadatos:

const authServerConfig = {
  metadata: {
    issuer: '<issuer-url>',
    // Los campos de metadatos deben estar en camelCase
    authorizationEndpoint: '<authorization-endpoint-url>',
    // ... otros campos de metadatos
  },
  type: 'oidc', // o 'oauth'
};

Paso 2: Configura los metadatos del recurso protegido​

Después de configurar los metadatos del servidor de autorización, necesitas inicializar MCPAuth como un Servidor de Recursos definiendo los metadatos de tus recursos protegidos.

Este paso sigue la especificación RFC 9728 (Metadatos de recursos protegidos OAuth 2.0) para describir tu servidor MCP como un recurso protegido:

import { MCPAuth } from 'mcp-auth';

// Define tu identificador de recurso
const resourceIdentifier = 'https://api.example.com/notes';

// Inicializa MCPAuth en modo servidor de recursos
const mcpAuth = new MCPAuth({
  protectedResources: {
    metadata: {
      resource: resourceIdentifier,
      authorizationServers: [authServerConfig], // Usando la configuración del Paso 1
      scopesSupported: ['read:notes', 'write:notes'],
    },
  },
});

Para múltiples recursos, puedes proporcionar un array de configuraciones de recursos protegidos, cada uno con su propia configuración de metadatos.

La configuración mostrada arriba cubre la configuración básica. Para parámetros de metadatos más avanzados, consulta la RFC 9728.

Paso 3: Monta el endpoint de metadatos del recurso protegido​

Monta el router para servir el endpoint de metadatos del recurso protegido. La ruta del endpoint se determina automáticamente por el componente de ruta de tu identificador de recurso:

  • Sin ruta: https://api.example.com → /.well-known/oauth-protected-resource
  • Con ruta: 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());