Habilitar el acceso de agentes de IA de terceros a tu servidor MCP

Esta guía te guía paso a paso para integrar Logto con tu servidor MCP usando mcp-auth, permitiéndote autenticar usuarios y recuperar de forma segura su información de identidad utilizando el flujo estándar de OpenID Connect.

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 un agente de IA de terceros (cliente MCP).

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

• Autenticar usuarios en tu tenant de Logto.
• Devolver reclamos de identidad (sub, username, name, email, etc.) para la invocación de la herramienta "whoami".

Diferencia entre agente de IA de terceros (cliente MCP) y tu propio cliente MCP

Veamos un ejemplo. Imagina que eres un desarrollador que ejecuta un servidor MCP para gestionar el acceso y la automatización del correo electrónico.

Aplicación de correo oficial (Tu propio cliente MCP)

• Proporcionas una aplicación de correo oficial para que los usuarios lean y gestionen sus correos electrónicos.
• Cómo funciona: La aplicación de correo oficial se conecta a tu servidor MCP usando Logto para autenticar a los usuarios. Cuando Alice inicia sesión, obtiene acceso automáticamente a sus correos electrónicos, sin pantallas de permisos adicionales, ya que es tu aplicación de confianza.

Agente de IA de terceros (Cliente MCP de terceros)

• Estás construyendo un ecosistema alrededor de tu servidor MCP, así que otro desarrollador crea “SmartMail AI” (un asistente de IA que puede resumir correos y programar reuniones automáticamente) integrándolo como cliente de terceros.
• Cómo funciona: SmartMail AI (cliente MCP de terceros) quiere acceder a los correos electrónicos de los usuarios a través de tu servidor MCP. Cuando Alice inicia sesión en SmartMail AI usando su cuenta:
  • Se le muestra una pantalla de consentimiento, solicitando permiso para que SmartMail AI lea sus correos y calendario.
  • Alice puede permitir o denegar este acceso.
  • Solo los datos a los que ella consiente son compartidos con SmartMail AI, y SmartMail AI no puede acceder a ningún dato adicional sin un nuevo consentimiento explícito.

Este control de acceso (permiso) garantiza la seguridad de los datos del usuario, incluso si tu servidor MCP gestiona todos los datos, las aplicaciones de terceros como SmartMail AI solo pueden acceder a lo que el usuario ha permitido explícitamente. No pueden eludir este proceso, ya que está reforzado por tu implementación de control de acceso en el servidor MCP.

Resumen

Tipo de cliente	Ejemplo	¿Requiere consentimiento?	¿Quién lo controla?
Aplicación de correo oficial	Tu propia aplicación de correo	No	Tú (el desarrollador)
Agente de IA de terceros	Asistente SmartMail AI	Sí	Otro desarrollador

nota:

Si deseas integrar tu servidor MCP con tu propio agente de IA o aplicación, consulta la guía Habilita autenticación para tus apps impulsadas por MCP con Logto.

Requisitos previos

• Un tenant de Logto Cloud (o autogestionado)
• Entorno Node.js o Python

Comprendiendo la arquitectura

• Servidor MCP: El servidor que expone herramientas y recursos a los clientes MCP.
• Cliente MCP: Un cliente utilizado para iniciar el flujo de autenticación y probar la integración. El agente de IA de terceros se usará como cliente en esta guía.
• Logto: Actúa como el proveedor de OpenID Connect (servidor de autorización) y gestiona las identidades de los usuarios.

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.

Configurar el agente de IA de terceros

Para habilitar que el agente de IA de terceros acceda a tu servidor MCP, debes configurar lo siguiente:

1. El cliente debe poder realizar solicitudes MCP para invocar las herramientas expuestas por el servidor MCP.
2. El cliente debe poder manejar la respuesta 401 No autorizado. Consulta Pasos del flujo de autorización para más detalles.
3. Tras la autenticación exitosa, el cliente debe poder realizar solicitudes al servidor MCP con el token de acceso obtenido de Logto.

Configurar el agente de IA en Logto

Para permitir que el agente de IA de terceros acceda a tu servidor MCP, debes configurar una aplicación de terceros en Logto. Esta aplicación se usará para representar al agente de IA y obtener las credenciales necesarias para la autenticación y autorización.

Permitir que los desarrolladores creen aplicaciones de terceros en Logto

Si estás construyendo un marketplace o quieres permitir que los desarrolladores creen aplicaciones de terceros en Logto, puedes aprovechar la Logto Management API para crear aplicaciones de terceros de forma programática. Esto permite a los desarrolladores registrar sus aplicaciones y obtener las credenciales necesarias para la autenticación.

Necesitarás alojar tu propio servicio para manejar el proceso de registro de clientes. Este servicio interactuará con la Logto Management API para crear aplicaciones de terceros en nombre de los desarrolladores.

Alternativamente, puedes crear manualmente aplicaciones de terceros en Logto Console para familiarizarte con el proceso.

Crear manualmente una aplicación de terceros en Logto

Puedes crear manualmente una aplicación de terceros en Logto Console para pruebas o integraciones puntuales. Esto es útil cuando quieres probar rápidamente la integración sin implementar un flujo completo de registro de clientes.

1. Inicia sesión en tu Logto Console.
2. Ve a Aplicaciones → Crear aplicación → Aplicación de terceros -> OIDC.
3. Rellena el nombre de la app y otros campos requeridos, luego haz clic en Crear aplicación.
4. Haz clic en la pestaña Permisos, en la sección Usuario, haz clic en "Agregar".
5. En el diálogo que se abre -> Datos de usuario -> selecciona los permisos profile, email, luego haz clic en Guardar.
6. En la aplicación de terceros, configura los alcances para solicitar los permisos openid profile email.
7. Configura la URI de redirección de tu aplicación de terceros según corresponda. Recuerda actualizar también la URI de redirección en Logto.

---

En el fondo, una aplicación de terceros es simplemente un cliente estándar de OAuth 2.0 / OIDC. Esto significa que tú (o el desarrollador de terceros) puedes usar cualquier biblioteca o framework de OAuth 2.0 / OIDC para integrarte con Logto.

Si no estás familiarizado con OAuth 2.0 o OIDC, puedes comenzar siguiendo una de nuestras guías rápidas de “Web tradicional”.

Algunas cosas a tener en cuenta:

1. Logto actualmente requiere que las aplicaciones de terceros sean aplicaciones de “Web tradicional”. En otras palabras, la aplicación necesita un servidor backend (o backend-for-frontend) para almacenar de forma segura el secreto del cliente.
2. La mayoría de nuestras guías rápidas están escritas para aplicaciones de primera parte, pero aún puedes usarlas como referencia para la integración de aplicaciones de terceros.
3. La principal diferencia es que las aplicaciones de terceros mostrarán una pantalla de consentimiento (Consent screen), solicitando a los usuarios permiso explícito para acceder a sus datos.

Puedes encontrar más información en nuestras guías rápidas.

Configura el servidor MCP

Crea el proyecto e instala las dependencias

Python

mkdir mcp-server
cd mcp-server
uv init # O utiliza tu propia estructura de proyecto
uv add "mcp[cli]" starlette uvicorn mcpauth # O utiliza cualquier gestor de paquetes preferido

Node.js

mkdir mcp-server
cd mcp-server
npm init -y
npm install @modelcontextprotocol/sdk express mcp-auth # O utiliza cualquier gestor de paquetes preferido

Configura la autenticación MCP con Logto

Recuerda reemplazar <your-logto-issuer-endpoint> por el endpoint del emisor que copiaste anteriormente.

Python

En whoami.py:

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

auth_issuer = '<your-logto-issuer-endpoint>'
auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC)
mcp_auth = MCPAuth(server=auth_server_config)

Node.js

En whoami.js:

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

const authIssuer = '<your-logto-issuer-endpoint>';
const mcpAuth = new MCPAuth({
  server: await fetchServerConfig(authIssuer, { type: 'oidc' }),
});

Implementa la verificación de tokens

Como vamos a verificar el token de acceso (Access token) y obtener la información del usuario, necesitamos implementar la verificación del token de acceso de la siguiente manera:

Python

import requests
from mcpauth.types import AuthInfo

def verify_access_token(token: str) -> AuthInfo:
    endpoint = auth_server_config.metadata.userinfo_endpoint
    response = requests.get(
        endpoint,
        headers={"Authorization": f"Bearer {token}"},
    )
    response.raise_for_status()
    data = response.json()
    return AuthInfo(
        token=token,
        subject=data.get("sub"),
        issuer=auth_server_config.metadata.issuer,
        claims=data,
    )

Node.js

const verifyToken = async (token) => {
  const { userinfoEndpoint, issuer } = mcpAuth.config.server.metadata;
  const response = await fetch(userinfoEndpoint, {
    headers: { Authorization: `Bearer ${token}` },
  });
  if (!response.ok) throw new Error('Token verification failed');
  const userInfo = await response.json();
  return {
    token,
    issuer,
    subject: userInfo.sub,
    claims: userInfo,
  };
};

Implementa la herramienta "whoami"

Ahora, vamos a implementar la herramienta "whoami" que devuelve los reclamos de identidad del usuario actual solicitando el endpoint userinfo con el token de acceso enviado por el cliente.

nota:

Estamos usando el transporte SSE para el ejemplo debido a la falta de soporte oficial para el transporte HTTP Streamable en la versión actual del SDK. Teóricamente, puedes usar cualquier transporte compatible con HTTP.

Python

from mcp.server.fastmcp import FastMCP
from starlette.applications import Starlette
from starlette.routing import Mount
from starlette.middleware import Middleware

mcp = FastMCP("WhoAmI")

@mcp.tool()
def whoami() -> dict:
    """
    Devuelve la información de identidad del usuario actual.
    """
    return (
        mcp_auth.auth_info.claims
        if mcp_auth.auth_info
        else {"error": "Not authenticated"}
    )

bearer_auth = Middleware(mcp_auth.bearer_auth_middleware(verify_access_token))
app = Starlette(
    routes=[
        mcp_auth.metadata_route(),  # Sirve metadatos OIDC para descubrimiento
        Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]),
    ],
)

Ejecuta el servidor con:

uvicorn whoami:app --host 0.0.0.0 --port 3001

Node.js

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

// Crea el servidor MCP y registra la herramienta whoami
const server = new McpServer({ name: 'WhoAmI', version: '0.0.0' });
server.tool('whoami', ({ authInfo }) => ({
  content: [
    { type: 'text', text: JSON.stringify(authInfo?.claims ?? { error: 'Not authenticated' }) },
  ],
}));

// Aplicación Express y middleware de MCP Auth
const app = express();
app.use(mcpAuth.delegatedRouter());
app.use(mcpAuth.bearerAuth(verifyToken));

// Transporte SSE (como en la documentación del SDK)
const transports = {};
app.get('/sse', async (_req, res) => {
  const transport = new SSEServerTransport('/messages', res);
  transports[transport.sessionId] = transport;
  res.on('close', () => delete transports[transport.sessionId]);
  await server.connect(transport);
});
app.post('/messages', async (req, res) => {
  const sessionId = String(req.query.sessionId);
  const transport = transports[sessionId];
  if (transport) await transport.handlePostMessage(req, res, req.body);
  else res.status(400).send('No transport found for sessionId');
});

app.listen(3001);

Ejecuta el servidor con:

node whoami.js

Probar la integración

1. Inicia el servidor MCP.
2. Inicia el agente de IA.
3. En el cliente, invoca la herramienta whoami para recuperar los reclamos de identidad del usuario actual.
4. El cliente debe manejar la respuesta 401 No autorizado y redirigir al usuario a Logto para autenticación.
5. Tras la autenticación exitosa, el cliente debe recibir un token de acceso y usarlo para realizar solicitudes al servidor MCP.
6. El cliente debe poder recuperar los reclamos de identidad del servidor MCP usando el token de acceso.

Python

El código completo del servidor MCP se puede encontrar en el repositorio mcp-auth/python.

Node.js

El código completo del servidor MCP se puede encontrar en el repositorio mcp-auth/js.