Saltar al contenido principal

Tutorial: ¿Quién soy? (Who am I?)

Este tutorial te guiará a través del proceso de configurar MCP Auth para autenticar usuarios y obtener su información de identidad desde el servidor de autorización.

Después de completar este tutorial, tendrás:

  • ✅ Una comprensión básica de cómo usar MCP Auth para autenticar usuarios.
  • ✅ Un servidor MCP que ofrece una herramienta para obtener información de identidad del usuario.

Descripción general​

El tutorial involucrará los siguientes componentes:

  • Servidor MCP: Un servidor MCP sencillo que utiliza los SDKs oficiales de MCP para manejar solicitudes.
  • Inspector MCP: Una herramienta visual de pruebas para servidores MCP. También actúa como un cliente OAuth / OIDC para iniciar el flujo de autorización y obtener tokens de acceso.
  • Servidor de autorización: Un proveedor OAuth 2.1 u OpenID Connect que gestiona identidades de usuario y emite tokens de acceso.

Aquí tienes un diagrama de alto nivel de la interacción entre estos componentes:

Comprende tu servidor de autorización​

Obtener información de identidad del usuario​

Para completar este tutorial, tu servidor de autorización debe ofrecer una API para obtener información de identidad del usuario:

Logto es un proveedor OpenID Connect que admite el endpoint userinfo estándar para obtener información de identidad del usuario.

Para obtener un token de acceso que pueda usarse para acceder al endpoint userinfo, se requieren al menos dos alcances: openid y profile. Puedes seguir leyendo, ya que cubriremos la configuración de alcances más adelante.

Registro dinámico de clientes​

El registro dinámico de clientes no es necesario para este tutorial, pero puede ser útil si deseas automatizar el proceso de registro del cliente MCP con tu servidor de autorización. Consulta ¿Es necesario el registro dinámico de clientes? para más detalles.

Configura el servidor MCP​

Usaremos los SDKs oficiales de MCP para crear un servidor MCP con una herramienta whoami que obtiene información de identidad del usuario desde el servidor de autorización.

Crea un nuevo proyecto​

mkdir mcp-server
cd mcp-server
uv init # O usa `pipenv` o `poetry` para crear un nuevo entorno virtual

Instala el SDK de MCP y dependencias​

pip install "mcp[cli]" starlette uvicorn

O cualquier otro gestor de paquetes que prefieras, como uv o poetry.

Crea el servidor MCP​

Primero, vamos a crear un servidor MCP que implemente una herramienta whoami.

Crea un archivo llamado whoami.py y añade el siguiente código:

from mcp.server.fastmcp import FastMCP
from starlette.applications import Starlette
from starlette.routing import Mount
from typing import Any

mcp = FastMCP("WhoAmI")

@mcp.tool()
def whoami() -> dict[str, Any]:
    """Una herramienta que retorna la información del usuario actual."""
    return {"error": "Not authenticated"}

app = Starlette(
    routes=[Mount('/', app=mcp.sse_app())]
)

Ejecuta el servidor con:

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

Inspecciona el servidor MCP​

Clona y ejecuta el inspector MCP​

Ahora que tenemos el servidor MCP en funcionamiento, podemos usar el inspector MCP para ver si la herramienta whoami está disponible.

Debido a la limitación de la implementación actual, hemos bifurcado el inspector MCP para hacerlo más flexible y escalable para autenticación y autorización. También hemos enviado un pull request al repositorio original para incluir nuestros cambios.

Para ejecutar el inspector MCP, puedes usar el siguiente comando (se requiere Node.js):

git clone https://github.com/mcp-auth/inspector.git
cd inspector
npm install
npm run dev

Luego, abre tu navegador y navega a http://localhost:6274/ (u otra URL mostrada en la terminal) para acceder al inspector MCP.

Conecta el inspector MCP al servidor MCP​

Antes de continuar, revisa la siguiente configuración en el inspector MCP:

  • Tipo de transporte: Establece en SSE.
  • URL: Establece la URL de tu servidor MCP. En nuestro caso, debería ser http://localhost:3001/sse.

Ahora puedes hacer clic en el botón "Connect" para ver si el inspector MCP puede conectarse al servidor MCP. Si todo está bien, deberías ver el estado "Connected" en el inspector MCP.

Punto de control: Ejecuta la herramienta whoami​

  1. En el menú superior del inspector MCP, haz clic en la pestaña "Tools".
  2. Haz clic en el botón "List Tools".
  3. Deberías ver la herramienta whoami listada en la página. Haz clic en ella para abrir los detalles de la herramienta.
  4. Deberías ver el botón "Run Tool" en el lado derecho. Haz clic en él para ejecutar la herramienta.
  5. Deberías ver el resultado de la herramienta con la respuesta JSON {"error": "Not authenticated"}.

Primera ejecución del inspector MCP

Integra con tu servidor de autorización​

Para completar esta sección, hay varias consideraciones a tener en cuenta:

La URL del emisor de tu servidor de autorización

Normalmente es la URL base de tu servidor de autorización, como https://auth.example.com. Algunos proveedores pueden tener una ruta como https://example.logto.app/oidc, así que asegúrate de consultar la documentación de tu proveedor.

Cómo obtener los metadatos del servidor de autorización
  • Si tu servidor de autorización cumple con OAuth 2.0 Authorization Server Metadata o OpenID Connect Discovery, puedes usar las utilidades integradas de MCP Auth para obtener los metadatos automáticamente.
  • Si tu servidor de autorización no cumple con estos estándares, deberás especificar manualmente la URL de metadatos o los endpoints en la configuración del servidor MCP. Consulta la documentación de tu proveedor para los endpoints específicos.
Cómo registrar el inspector MCP como cliente en tu servidor de autorización
  • Si tu servidor de autorización admite registro dinámico de clientes, puedes omitir este paso ya que el inspector MCP se registrará automáticamente como cliente.
  • Si tu servidor de autorización no admite el registro dinámico de clientes, deberás registrar manualmente el inspector MCP como cliente en tu servidor de autorización.
Cómo obtener información de identidad del usuario y cómo configurar los parámetros de la solicitud de autorización

  • Para proveedores OpenID Connect: normalmente necesitas solicitar al menos los alcances openid y profile al iniciar el flujo de autorización. Esto asegurará que el token de acceso devuelto por el servidor de autorización contenga los alcances necesarios para acceder al endpoint userinfo y obtener información de identidad del usuario.

    Nota: Algunos proveedores pueden no admitir el endpoint userinfo.

  • Para proveedores OAuth 2.0 / OAuth 2.1: consulta la documentación de tu proveedor para ver cómo obtener información de identidad del usuario usando un token de acceso y qué parámetros se requieren para obtener dicho token al invocar el flujo de autorización.

Aunque cada proveedor puede tener sus propios requisitos específicos, los siguientes pasos te guiarán en el proceso de integración del inspector MCP y el servidor MCP con configuraciones específicas del proveedor.

Registra el inspector MCP como cliente​

Integrar con Logto es sencillo, ya que es un proveedor OpenID Connect que admite el endpoint userinfo estándar para obtener información de identidad del usuario.

Como Logto aún no admite el registro dinámico de clientes, deberás registrar manualmente el inspector MCP como cliente en tu tenant de Logto:

  1. Abre tu inspector MCP, haz clic en el botón "OAuth Configuration". Copia el valor de Redirect URL (auto-populated), que debería ser algo como http://localhost:6274/oauth/callback.
  2. Inicia sesión en Logto Console (o tu instancia autoalojada de Logto Console).
  3. Navega a la pestaña "Applications", haz clic en "Create application". En la parte inferior de la página, haz clic en "Create app without framework".
  4. Completa los detalles de la aplicación y haz clic en "Create application":
    • Selecciona un tipo de aplicación: Elige "Single-page application".
    • Nombre de la aplicación: Ingresa un nombre para tu aplicación, por ejemplo, "MCP Inspector".
  5. En la sección "Settings / Redirect URIs", pega el valor de Redirect URL (auto-populated) que copiaste del inspector MCP. Luego haz clic en "Save changes" en la barra inferior.
  6. En la tarjeta superior, verás el valor "App ID". Cópialo.
  7. Vuelve al inspector MCP y pega el valor "App ID" en la sección "OAuth Configuration" bajo "Client ID".
  8. Ingresa el valor {"scope": "openid profile email"} en el campo "Auth Params". Esto asegurará que el token de acceso devuelto por Logto contenga los alcances necesarios para acceder al endpoint userinfo.

Configura MCP Auth​

En tu proyecto del servidor MCP, necesitas instalar el SDK de MCP Auth y configurarlo para usar los metadatos de tu servidor de autorización.

Primero, instala el paquete mcpauth:

pip install mcpauth

O cualquier otro gestor de paquetes que prefieras, como uv o poetry.

MCP Auth requiere los metadatos del servidor de autorización para poder inicializarse. Dependiendo de tu proveedor:

La URL del emisor se puede encontrar en la página de detalles de tu aplicación en Logto Console, en la sección "Endpoints & Credentials / Issuer endpoint". Debería verse como https://my-project.logto.app/oidc.

Actualiza el archivo whoami.py para incluir la configuración de MCP Auth:

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

auth_issuer = '<issuer-endpoint>'  # Reemplaza con tu endpoint de emisor
auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC)
mcp_auth = MCPAuth(server=auth_server_config)

Ahora, necesitamos crear un verificador personalizado de token de acceso (Access token) que obtendrá la información de identidad del usuario desde el servidor de autorización utilizando el token de acceso proporcionado por el inspector MCP.

import pydantic
import requests
from mcpauth.exceptions import (
    MCPAuthTokenVerificationException,
    MCPAuthTokenVerificationExceptionCode,
)
from mcpauth.types import AuthInfo

def verify_access_token(token: str) -> AuthInfo:
    """
    Verifica el token Bearer proporcionado obteniendo la información del usuario desde el servidor de autorización.
    Si el token es válido, retorna un objeto `AuthInfo` que contiene la información del usuario.

    :param token: El token Bearer recibido del inspector MCP.
    """

    issuer = auth_server_config.metadata.issuer
    endpoint = auth_server_config.metadata.userinfo_endpoint # El proveedor debe soportar el endpoint userinfo
    if not endpoint:
        raise ValueError(
            "El endpoint userinfo no está configurado en los metadatos del servidor de autenticación."
        )

    try:
        response = requests.get(
            endpoint,
            headers={"Authorization": f"Bearer {token}"}, # Encabezado estándar para token Bearer
        )
        response.raise_for_status() # Asegura que se lance un error para errores HTTP
        json = response.json() # Analiza la respuesta JSON
        return AuthInfo(
            token=token,
            subject=json.get("sub"), # 'sub' es un reclamo estándar para el sujeto (ID del usuario)
            issuer=issuer, # Usa el emisor de los metadatos
            claims=json, # Incluye todos los reclamos (campos JSON) retornados por el endpoint userinfo
        )
    # `AuthInfo` es un modelo de Pydantic, así que los errores de validación usualmente significan que la respuesta no coincide
    # con la estructura esperada
    except pydantic.ValidationError as e:
        raise MCPAuthTokenVerificationException(
            MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN,
            cause=e,
        )
    # Maneja otras excepciones que puedan ocurrir durante la solicitud
    except Exception as e:
        raise MCPAuthTokenVerificationException(
            MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED,
            cause=e,
        )

Actualiza el servidor MCP​

¡Ya casi terminamos! Es momento de actualizar el servidor MCP para aplicar la ruta y función middleware de MCP Auth, y luego hacer que la herramienta whoami retorne la información real de identidad del usuario.

@mcp.tool()
def whoami() -> dict[str, Any]:
    """Una herramienta que retorna la información del usuario actual."""
    return (
        mcp_auth.auth_info.claims
        if mcp_auth.auth_info # Esto será poblado por el middleware Bearer auth
        else {"error": "Not authenticated"}
    )

# ...

bearer_auth = Middleware(mcp_auth.bearer_auth_middleware(verify_access_token))
app = Starlette(
    routes=[
        # Añade la ruta de metadatos (`/.well-known/oauth-authorization-server`)
        mcp_auth.metadata_route(),
        # Protege el servidor MCP con el middleware Bearer auth
        Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]),
    ],
)

Punto de control: Ejecuta la herramienta whoami con autenticación​

Reinicia tu servidor MCP y abre el inspector MCP en tu navegador. Cuando hagas clic en el botón "Connect", deberías ser redirigido a la página de inicio de sesión de tu servidor de autorización.

Una vez que inicies sesión y regreses al inspector MCP, repite las acciones que hicimos en el punto de control anterior para ejecutar la herramienta whoami. Esta vez, deberías ver la información de identidad del usuario retornada por el servidor de autorización.

Resultado de la herramienta whoami en el inspector MCP

info

Consulta el repositorio del SDK de MCP Auth para Python para ver el código completo del servidor MCP (versión OIDC).

Notas finales​

🎊 ¡Felicidades! Has completado exitosamente el tutorial. Recapitulemos lo que hemos hecho:

  • Configuración de un servidor MCP básico con la herramienta whoami
  • Integración del servidor MCP con un servidor de autorización usando MCP Auth
  • Configuración del Inspector MCP para autenticar usuarios y obtener su información de identidad

También puedes explorar algunos temas avanzados, incluyendo:

Asegúrate de consultar otros tutoriales y documentación para sacar el máximo provecho de MCP Auth.