Saltar al contenido principal

Comenzar

Soporte para la especificación de autorización MCP

Esta versión es compatible con la especificación de autorización MCP (versión 2025-06-18).

SDK de Python disponible

¡MCP Auth también está disponible para Python! Consulta el repositorio del SDK de Python para instalación y uso.

Elige un proveedor compatible con OAuth 2.1 u OpenID Connect​

La especificación MCP tiene requisitos específicos para la autorización. El mecanismo de autorización se basa en especificaciones establecidas, implementando un subconjunto seleccionado de sus características para garantizar la seguridad e interoperabilidad, manteniendo la simplicidad:

Estas especificaciones trabajan juntas para proporcionar un marco de autorización seguro y estandarizado para implementaciones MCP.

Puedes consultar la lista de proveedores compatibles con MCP para ver si tu proveedor es compatible.

Instala el SDK de MCP Auth​

pnpm add mcp-auth

Inicializa MCP Auth​

El primer paso es definir tu identificador de recurso y configurar el servidor de autorización que será de confianza para la autenticación. MCP Auth ahora opera en modo servidor de recursos, conforme a la especificación MCP actualizada que requiere OAuth 2.0 Protected Resource Metadata (RFC 9728).

Si tu proveedor cumple con:

Puedes usar la función incorporada para obtener los metadatos e inicializar la instancia de MCP Auth:

import { MCPAuth, fetchServerConfig } from 'mcp-auth';

// 1. Define tu identificador de recurso y obtén la configuración para su servidor de autorización de confianza.
const resourceIdentifier = 'https://api.example.com/notes';
const authServerConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' });

// 2. Inicializa MCPAuth en modo servidor de recursos.
// `protectedResources` puede ser un solo objeto o un array para múltiples recursos.
const mcpAuth = new MCPAuth({
  protectedResources: {
    metadata: {
      resource: resourceIdentifier,
      authorizationServers: [authServerConfig],
      scopesSupported: ['read:notes', 'write:notes'],
    },
  },
});

Si utilizas entornos edge como Cloudflare Workers donde no se permite el fetch asíncrono a nivel superior, utiliza el descubrimiento bajo demanda:

const authServerConfig = { issuer: 'https://auth.logto.io/oidc', type: 'oidc' };

Para otras formas de configurar los metadatos del servidor de autorización, incluyendo URLs de metadatos personalizadas, transpilación de datos o especificación manual de metadatos, consulta Otras formas de configurar MCP Auth.

Monta el endpoint de metadatos del recurso protegido​

Para cumplir con la especificación MCP actualizada, MCP Auth monta el endpoint OAuth 2.0 Protected Resource Metadata (RFC 9728) en tu servidor MCP. Este endpoint permite a los clientes descubrir:

  • Qué servidores de autorización pueden emitir tokens válidos para tus recursos protegidos
  • Qué alcances (scopes) son compatibles para cada recurso
  • Otros metadatos requeridos para la validación adecuada de tokens

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

El servidor MCP ahora funciona como un servidor de recursos que valida tokens y proporciona metadatos sobre sus recursos protegidos, confiando completamente en servidores de autorización externos para la autenticación y autorización.

Puedes usar el método proporcionado por el SDK para montar este endpoint:

import express from 'express';

const app = express();

// Monta el router para servir los metadatos del recurso protegido.
// Para el recurso "https://api.example.com" → endpoint: /.well-known/oauth-protected-resource
// Para el recurso "https://api.example.com/notes" → endpoint: /.well-known/oauth-protected-resource/notes
app.use(mcpAuth.protectedResourceMetadataRouter());

Usa el middleware Bearer auth​

Una vez inicializada la instancia de MCP Auth, puedes aplicar el middleware Bearer auth para proteger tus rutas MCP. El middleware ahora requiere especificar a qué recurso pertenece el endpoint, permitiendo una validación adecuada del token:

Validación de audiencia

El parámetro audience es requerido por la especificación OAuth 2.0 para una validación segura de tokens. Sin embargo, actualmente es opcional para mantener la compatibilidad con servidores de autorización que aún no admiten identificadores de recursos. Por razones de seguridad, por favor incluye siempre el parámetro audience cuando sea posible. Las versiones futuras harán obligatoria la validación de audiencia para cumplir completamente con la especificación.

Siempre valida los alcances (Scopes)

En OAuth 2.0, los alcances (scopes) son el mecanismo principal para el control de permisos. Un token válido con la audience correcta NO garantiza que el usuario tenga permiso para realizar una acción: los servidores de autorización pueden emitir tokens con un alcance vacío o limitado.

Utiliza siempre requiredScopes para asegurar que el token contiene los permisos necesarios para cada operación. Nunca asumas que un token válido implica acceso completo.

import express from 'express';

const app = express();

// Monta el router para servir los metadatos del recurso protegido.
app.use(mcpAuth.protectedResourceMetadataRouter());

// Protege un endpoint de API usando la política específica del recurso.
app.get(
  '/notes',
  mcpAuth.bearerAuth('jwt', {
    resource: resourceIdentifier,
    audience: resourceIdentifier,  // Habilita la validación de audiencia por seguridad
    requiredScopes: ['read:notes'],
  }),
  (req, res) => {
    // Si el token es válido, `req.auth` se rellena con sus reclamos.
    console.log('Información de autenticación:', req.auth);
    res.json({ notes: [] });
  },
);

app.listen(3000);

En los ejemplos anteriores, especificamos el tipo de token jwt y el identificador de recurso. El middleware validará automáticamente el token JWT contra los servidores de autorización de confianza configurados para ese recurso específico y rellenará la información del usuario autenticado.

info

¿Nunca has oído hablar de JWT (JSON Web Token)? No te preocupes, puedes seguir leyendo la documentación y lo explicaremos cuando sea necesario. También puedes consultar Auth Wiki para una introducción rápida.

Para más información sobre la configuración de Bearer auth, consulta Configurar Bearer auth.

Recupera la información de autenticación en tu implementación MCP​

Una vez aplicado el middleware Bearer auth, puedes acceder a la información del usuario autenticado (o identidad) en tu implementación MCP:

El segundo argumento del handler de la herramienta contendrá el objeto authInfo, que incluye la información del usuario autenticado:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

const server = new McpServer(/* ... */);

// Inicializa con MCP Auth como se muestra en los ejemplos anteriores
// ...

server.registerTool(
  'add',
  {
    description: 'Suma dos números',
    inputSchema: { a: z.number(), b: z.number() },
  },
  async ({ a, b }, { authInfo }) => {
    // Ahora puedes usar el objeto `authInfo` para acceder a la información autenticada
  }
);

Próximos pasos​

Continúa leyendo para aprender un ejemplo de extremo a extremo sobre cómo integrar MCP Auth con tu servidor MCP y cómo manejar el flujo de autenticación en clientes MCP.