Habilita autenticación para tus apps impulsadas por MCP con Logto

tip:

Explora las soluciones de IA de Logto: autenticación (Authentication) y autorización (Authorization) para servidores MCP, agentes de IA y aplicaciones.

Esta guía te guía paso a paso para integrar Logto con tu servidor MCP usando mcp-auth y el SDK oficial de MCP v2, permitiéndote autenticar usuarios y leer de forma segura su identidad verificada desde el token de acceso.

Aprenderás a:

Configurar Logto como el servidor de autorización para tu servidor MCP.
Configurar una herramienta “whoami” en tu servidor MCP para devolver los reclamos de identidad del usuario actual.
Probar el flujo con VS Code (cliente MCP).

Después de este tutorial, tu servidor MCP podrá:

Autenticar usuarios en tu tenant de Logto.
Verificar tokens de acceso JWT emitidos por Logto (firma, emisor, audiencia y expiración).
Devolver los reclamos de identidad verificados (sub, iss, aud, etc.) para la invocación de la herramienta "whoami".

Una vez completada la integración, puedes reemplazar VS Code por tu propio cliente MCP, como una aplicación web, para acceder a las herramientas y recursos expuestos por tu servidor MCP.

Código de ejemplo:

El código de ejemplo completo y ejecutable para esta guía se puede encontrar en el repositorio mcp-auth/js:

whoami-express: el servidor "whoami" de esta guía, en Node.js con Express.
whoami: el mismo servidor construido con fetch-native (Request / Response estándar web con Hono), desplegable en Cloudflare Workers.

Requisitos previos

Un tenant de Logto Cloud (o autogestionado)
Entorno Node.js >= 20

Entendiendo la arquitectura

Servidor MCP: El servidor que expone herramientas y recursos a los clientes MCP. Siguiendo la última especificación de MCP, actúa como un servidor de recursos OAuth 2.0 que valida los tokens de acceso emitidos por Logto.
Cliente MCP: Un cliente utilizado para iniciar el flujo de autenticación y probar la integración. Usaremos VS Code (con soporte MCP integrado) como cliente en esta guía.
Logto: Funciona como el proveedor de OpenID Connect (servidor de autorización), gestiona las identidades de los usuarios y emite tokens de acceso JWT ligados a la audiencia para tu servidor MCP.

Un diagrama de secuencia no normativo ilustra el flujo general del proceso:

nota:

Debido a que MCP está evolucionando rápidamente, el diagrama anterior puede no estar completamente actualizado. Por favor, consulta la documentación de mcp-auth para la información más reciente.

Configura la app en Logto

Tu cliente MCP debe estar registrado como una aplicación en Logto para iniciar el flujo de autorización. Registraremos VS Code como el cliente en esta guía:

Inicia sesión en tu Consola de Logto.
Ve a Aplicaciones → Crear aplicación → Crear app sin framework.
Elige tipo: App nativa.
Rellena el nombre de la app (por ejemplo, "VS Code") y otros campos requeridos, luego haz clic en Crear aplicación.
En la sección Configuración / URIs de redirección, añade los siguientes URIs de redirección para VS Code y guarda los cambios:
```
http://127.0.0.1
https://vscode.dev/redirect
```
Guarda y copia el ID de la app y el endpoint del emisor.

Configura el servidor MCP

Usaremos el SDK oficial de MCP v2 y mcp-auth para crear un servidor MCP con una herramienta "whoami" que devuelve los reclamos de identidad del usuario actual.

Crea el proyecto e instala las dependencias

mkdir mcp-server
cd mcp-server
npm init -y
npm pkg set type="module"
npm pkg set main="whoami.js"
npm pkg set scripts.start="node whoami.js"
npm install @modelcontextprotocol/server @modelcontextprotocol/express @modelcontextprotocol/node express mcp-auth

@modelcontextprotocol/server es el SDK principal de MCP v2, que utiliza los estándares web Request / Response.
@modelcontextprotocol/express y @modelcontextprotocol/node lo adaptan a Express en Node.js.
mcp-auth proporciona el verificador de tokens y los metadatos de descubrimiento OAuth para el SDK de MCP.

nota:

El SDK v2 de MCP y mcp-auth son solo ESM y requieren Node.js >= 20.

Registra el servidor MCP como un recurso de API

La especificación más reciente de MCP requiere que los tokens de acceso estén vinculados al recurso para el que se emiten (RFC 8707), y mcp-auth lo aplica: el reclamo aud del token debe coincidir con el identificador de recurso de tu servidor MCP. En Logto, esto se hace creando un recurso de API cuyo indicador coincida con la URL de tu servidor MCP:

Inicia sesión en tu Logto Console.
Ve a Recursos de API (API resources) → Crear recurso de API (Create API resource).
Rellena los detalles y haz clic en Crear recurso de API (Create API resource):
- Nombre de la API (API name): Ingresa un nombre, por ejemplo, "Who am I".
- Identificador de la API (API identifier): Ingresa http://localhost:3001/. Debe coincidir con el identificador de recurso que configuraremos en el servidor MCP.

Barra diagonal al final en el indicador de recurso:

Incluye siempre una barra diagonal (/) al final del indicador de recurso. Debido a un error actual en el SDK oficial de MCP, los clientes que usan el SDK agregarán automáticamente una barra diagonal al final de los identificadores de recurso al iniciar solicitudes de autenticación. Si tu indicador de recurso no incluye la barra diagonal, la validación del recurso fallará para esos clientes.

Configura MCP Auth con Logto

Declara tu servidor MCP como un recurso protegido: su identificador de recurso y el servidor de autorización en el que confía. Recuerda reemplazar <your-logto-issuer-endpoint> con el endpoint del emisor que copiaste anteriormente (se encuentra en la página de detalles de la aplicación bajo Endpoints & Credentials, por ejemplo, https://my-project.logto.app/oidc).

En whoami.js:

import { MCPAuth } from 'mcp-auth';

const authIssuer = '<your-logto-issuer-endpoint>';

const mcpAuth = new MCPAuth({
  protectedResourceMetadata: {
    // El identificador de recurso; debe coincidir con el indicador de recurso de API registrado en Logto
    resource: 'http://localhost:3001/',
    // El servidor de autorización en el que confía este servidor MCP
    authorizationServer: { issuer: authIssuer, type: 'oidc' },
  },
});

Los metadatos del servidor de autorización se obtienen de forma diferida la primera vez que se necesitan y se almacenan en caché después. La instancia de MCPAuth verifica los tokens de acceso JWT contra el JWKS de Logto: la firma, el emisor, la audiencia y la expiración se aplican. No es necesario realizar una verificación manual de tokens.

Implementa la herramienta "whoami"

Ahora, implementemos la herramienta "whoami" que devuelve los reclamos de identidad del usuario actual a partir del token de acceso verificado. Usa getAuthInfo para leer la información de autenticación que mcp-auth ha verificado desde el contexto del callback de la herramienta.

import { McpServer } from '@modelcontextprotocol/server';
import { getAuthInfo } from 'mcp-auth';

// Función de fábrica para crear una instancia del servidor MCP
// Cada solicitud obtiene su propia instancia del servidor, manteniendo las solicitudes aisladas
const createMcpServer = () => {
  const mcpServer = new McpServer({
    name: 'WhoAmI',
    version: '0.0.0',
  });

  // Añade una herramienta al servidor que devuelve la información del usuario actual
  mcpServer.registerTool(
    'whoami',
    {
      description: 'Obtener la información del usuario actual',
    },
    (context) => {
      const { claims } = getAuthInfo(context);
      return {
        content: [{ type: 'text', text: JSON.stringify(claims) }],
      };
    }
  );

  return mcpServer;
};

Conecta el servidor

Por último, sirve los documentos de descubrimiento OAuth (RFC 9728 / RFC 8414) para que los clientes MCP puedan encontrar tu servidor de autorización, y protege el endpoint MCP con el middleware Bearer auth del SDK.

import {
  createMcpExpressApp,
  mcpAuthMetadataRouter,
  requireBearerAuth,
} from '@modelcontextprotocol/express';
import { toNodeHandler } from '@modelcontextprotocol/node';
import { createMcpHandler } from '@modelcontextprotocol/server';

const PORT = 3001;

// El handler MCP utiliza los estándares web Request / Response; `toNodeHandler` lo adapta a Express
const mcpNodeHandler = toNodeHandler(createMcpHandler(createMcpServer));

const app = createMcpExpressApp();

// Sirve los documentos de descubrimiento OAuth (`/.well-known/...`), públicos por diseño
app.use(mcpAuthMetadataRouter(await mcpAuth.getAuthMetadataOptions()));

app.all(
  '/',
  // Requiere un token Bearer válido; la información de autenticación verificada fluye al handler vía `req.auth`
  requireBearerAuth(mcpAuth.getBearerAuthOptions()),
  // `createMcpExpressApp` aplica `express.json()`, que consume el stream de la solicitud, por lo que el
  // cuerpo parseado se pasa explícitamente
  async (request, response) => mcpNodeHandler(request, response, request.body)
);

app.listen(PORT);

Ejecuta el servidor con:

npm start

Prueba la integración

Inicia el servidor MCP:
```
npm start
```
Conecta VS Code a tu servidor MCP:
1. Pulsa Command + Shift + P (macOS) o Ctrl + Shift + P (Windows / Linux) para abrir la paleta de comandos.
2. Escribe MCP: Add Server... y selecciónalo.
3. Elige HTTP como tipo de servidor.
4. Ingresa la URL del servidor MCP: http://localhost:3001/
5. Cuando comience el flujo OAuth, VS Code solicitará el Client ID: pega el ID de la app que copiaste antes.
6. Como es un cliente público sin secreto de app, simplemente pulsa Enter para omitir el secreto.
7. Completa el flujo de inicio de sesión en tu navegador.
Después de iniciar sesión, ejecuta la herramienta whoami en VS Code.

Deberías ver los reclamos verificados del token de acceso, como:

{
  "iss": "https://my-project.logto.app/oidc",
  "sub": "user_XXXX",
  "aud": "http://localhost:3001/",
  "client_id": "<your-app-id>"
}

Más información

Tu servidor MCP ahora verifica los tokens de acceso entrantes. Como siguiente paso, aprende cómo puede llamar de forma segura a tus APIs empresariales downstream en nombre de los usuarios, sin pasar tokens ni perder el contexto del usuario:

Cómo un servidor MCP llama a tu API en nombre de los usuarios: una estrategia de tokens para producción

Requisitos previos​

Entendiendo la arquitectura​

Configura la app en Logto​

Configura el servidor MCP​

Crea el proyecto e instala las dependencias​

Registra el servidor MCP como un recurso de API​

Configura MCP Auth con Logto​

Implementa la herramienta "whoami"​

Conecta el servidor​

Prueba la integración​

Más información​