Comenzar

Elige un proveedor compatible con OAuth 2.1 u OpenID Connect

La especificación MCP tiene algunos requisitos específicos para la autorización:

• OAuth 2.1 IETF DRAFT
• Metadatos del servidor de autorización OAuth 2.0 (RFC 8414)
• Protocolo de registro dinámico de clientes OAuth 2.0 (RFC 7591)

Aunque los dos últimos no son obligatorios, el primero es necesario para garantizar una implementación segura y conforme.

nota

En el nuevo borrador de MCP, RFC 8414 será obligatorio para los servidores de autorización (proveedores). Actualizaremos la documentación una vez que el nuevo borrador esté finalizado.

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 inicializar la instancia de MCP Auth con los metadatos del servidor de autorización de tu proveedor. Si tu proveedor cumple con uno de estos:

• Metadatos del servidor de autorización OAuth 2.0
• 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
from mcpauth.utils import fetch_server_config

mcp_auth = MCPAuth(
    server=fetch_server_config(
      '<auth-server-url>',
      type=AuthServerType.OIDC # o AuthServerType.OAUTH
    )
)

Node.js

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

const mcpAuth = new MCPAuth({
  server: await fetchServerConfig('<auth-server-issuer>', { type: 'oidc' }), // o 'oauth'
});

Si necesitas especificar manualmente la URL de los metadatos o los endpoints, consulta Otras formas de inicializar MCP Auth.

Monta el endpoint de metadatos

Para cumplir con la especificación MCP actual, MCP Auth monta el endpoint de Metadatos del Servidor de Autorización OAuth 2.0 (/.well-known/oauth-authorization-server) en tu servidor MCP:

Python

from starlette.applications import Starlette

app = Starlette(routes=[
    mcp_auth.metadata_route(),
])

Node.js

import express from 'express';

const app = express();
app.use(mcpAuth.delegatedRouter());

Las URLs en los metadatos se mantienen tal cual, por lo que el rol de servidor de autorización se delega completamente al proveedor. Puedes probar el endpoint de metadatos visitando /.well-known/oauth-authorization-server en tu servidor MCP.

¿Por qué solo el endpoint de metadatos?

Puede que veas que los SDK oficiales proporcionan un router de autenticación que monta endpoints de autorización como /authorize, /token, etc. Aquí te explicamos por qué no hacemos eso:

1. Montar solo el endpoint de metadatos te permite aprovechar todas las capacidades de tu proveedor sin "reinventar la rueda" e inyectar complejidad innecesaria en tu servidor MCP.
2. También hay un esfuerzo en curso para cambiar el rol del servidor MCP a un servidor de recursos y requerir Metadatos de Recursos Protegidos OAuth 2.0 (RFC 9728). Lo que significa que el servidor MCP ya no manejará ninguna lógica de autorización (incluido el endpoint de metadatos), sino que solo servirá como un servidor de recursos que depende del proveedor para la autenticación y autorización.

nota

Actualizaremos MCP Auth para soportar la nueva especificación MCP cuando esté finalizada. Mientras tanto, puedes usar la versión actual que es compatible con la especificación vigente.

Usa el middleware Bearer auth

Una vez que la instancia de MCP Auth está inicializada, puedes aplicar el middleware Bearer auth para proteger tus rutas MCP:

Python

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

mcp = FastMCP()
mcp_auth = MCPAuth(
  # Inicializa con la configuración de tu servidor de autenticación
)
bearer_auth = mcp_auth.bearer_auth_middleware(
    "jwt", required_scopes=["read", "write"]
)

app = Starlette(routes=[
    mcp_auth.metadata_route(),
    Mount(
        "/",
        app=mcp.sse_app(),
        middleware=[Middleware(bearer_auth)],
    ),
])

Node.js

import express from 'express';
import { MCPAuth } from 'mcp-auth';

const app = express();
const server = new McpServer(/* ... */);
const mcpAuth = new MCPAuth({
  /* ... */
});

app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }));

En el ejemplo anterior, especificamos el tipo de token jwt y requerimos los alcances read y write. Validará automáticamente el JWT (JSON Web Token) y rellenará un objeto con la información del usuario autenticado.

info

¿No 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 la 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()
mcp_auth = MCPAuth(
  # Inicializa con la configuración de tu servidor de autenticación
)

@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(/* ... */);
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.