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).

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 seguridad e interoperabilidad, manteniendo la simplicidad:

• OAuth 2.1 IETF DRAFT (draft-ietf-oauth-v2-1-13)
• OAuth 2.0 Authorization Server Metadata (RFC 8414)
• OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591)
• OAuth 2.0 Protected Resource Metadata (RFC 9728)

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 MCP Auth SDK

MCP Auth está disponible tanto para Python como para TypeScript. ¡Avísanos si necesitas soporte para otro lenguaje o framework!

Python

pip install mcpauth

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

Node.js

npm install mcp-auth

O cualquier otro gestor de paquetes que prefieras, como pnpm o yarn.

Inicializa MCP Auth

El primer paso es definir tu identificador de recurso y configurar el servidor de autorización que será confiable 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:

• OAuth 2.0 Authorization Server Metadata
• OpenID Connect Discovery

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

Python

from mcpauth import MCPAuth
from mcpauth.config import AuthServerType, ResourceServerConfig, ResourceServerMetadata
from mcpauth.utils import fetch_server_config

# 1. Define tu identificador de recurso y obtén la configuración de su servidor de autorización confiable.
resource_id = "https://api.example.com/notes"
auth_server_config = fetch_server_config("https://auth.logto.io/oidc", AuthServerType.OIDC)

# 2. Inicializa MCPAuth en modo servidor de recursos.
# `protected_resources` puede ser un solo objeto o una lista para múltiples recursos.
mcp_auth = MCPAuth(
    protected_resources=ResourceServerConfig(
        metadata=ResourceServerMetadata(
            resource=resource_id,
            authorization_servers=[auth_server_config],
            scopes_supported=[
                "read:notes",
                "write:notes",
            ],
        )
    )
)

Node.js

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

// 1. Define tu identificador de recurso y obtén la configuración de su servidor de autorización confiable.
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'],
      },
    },
  ],
});

Para otras formas de configurar los metadatos del servidor de autorización, incluyendo URLs de metadatos personalizadas, transpile 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:

Python

from starlette.applications import Starlette

# 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 = Starlette(routes=[
    *mcp_auth.resource_metadata_router().routes,
])

Node.js

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 la validación adecuada del token:

Validación de audiencia (Audience Validation)

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.

Python

from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.routing import Mount

# Crea el middleware para proteger tu servidor MCP con la política específica del recurso.
bearer_auth = Middleware(mcp_auth.bearer_auth_middleware('jwt', 
    resource=resource_id,
    audience=resource_id,  # Habilita la validación de audiencia por seguridad
    required_scopes=['read:notes']
))

# Monta el router para servir los metadatos del recurso protegido y proteger el servidor MCP.
app = Starlette(
    routes=[
        *mcp_auth.resource_metadata_router().routes,
        # Protege el servidor MCP con el middleware Bearer auth.
        Mount("/", app=mcp.sse_app(), middleware=[bearer_auth]),
    ],
)

Node.js

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 (claims).
    console.log('Auth info:', 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 confiables 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) antes? 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:

Python

MCP Auth almacenará la información del usuario autenticado en una variable de contexto tras una autenticación exitosa una vez aplicado el middleware Bearer auth. Puedes acceder a ella en tus handlers de herramientas MCP así:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP()

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

@mcp.tool()
def add(a: int, b: int):
    """
    Una herramienta que suma dos números.
    La información del usuario autenticado estará disponible en el contexto.
    """
    auth_info = mcp_auth.auth_info # Accede a la información de autenticación en el contexto actual
    if auth_info:
        print(f"Usuario autenticado: {auth_info.claims}")
    return a + b

Node.js

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.tool('add', { 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 los clientes MCP.