MCP OAuth 2.0: autentica tu servidor de herramientas
Montas el servidor MCP. Registras las herramientas. El agente las llama y funciona. En local, sin más.
Subes eso a producción y acabas de publicar una API sin autenticación. Cualquier cliente que conozca el endpoint tiene acceso completo a todas las herramientas que registraste.
Este es el error más común al llevar un servidor MCP de demo a producción: la especificación soporta OAuth 2.0 desde la versión 2025-11-05, pero la mayoría de tutoriales no llegan a esa parte.
Por qué un servidor MCP sin auth es un problema de arquitectura
No es un problema de seguridad menor. Un servidor MCP expuesto sin autenticación tiene consecuencias concretas en producción:
Sin saber quién llama, no puedes filtrar herramientas por cliente. Si un tenant A y un tenant B comparten el mismo servidor, ambos tienen acceso a las mismas herramientas con los mismos permisos. El artículo anterior sobre RBAC dinámico en agentes IA cubre el filtrado por rol, pero ese filtrado necesita saber quién es el caller antes de poder aplicarse.
Sin tokens, no puedes auditar. Cuando algo falla —y fallará—, necesitas saber qué cliente llamó qué herramienta con qué parámetros. Sin identidad en la petición, el log solo te dice que send_invoice() se ejecutó 400 veces. No quién la llamó.
Sin expiración de tokens, el acceso es permanente. Una credencial comprometida que no caduca es una puerta abierta indefinida.
La especificación MCP OAuth 2.0
El protocolo define dos flujos según el tipo de cliente:
Public clients (Claude Desktop, aplicaciones sin servidor propio): Authorization Code con PKCE. El cliente redirige al usuario al Authorization Server, obtiene un código, lo intercambia por un access token.
Confidential clients (servidores que llaman a tu MCP desde backend): Client Credentials. El servidor se autentica directamente con client_id y client_secret, obtiene un access token sin interacción de usuario.
En ambos casos, cada petición al servidor MCP lleva el token en la cabecera:
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...
Y el servidor MCP valida ese token antes de ejecutar ninguna herramienta.
Implementación: middleware de validación en TypeScript
El patrón más limpio es validar el token en un middleware antes de que el router MCP lo procese. Aquí el middleware para un servidor Next.js con validación JWT:
import { jwtVerify, createRemoteJWKSet } from 'jose'
import type { NextRequest } from 'next/server'
const JWKS = createRemoteJWKSet(
new URL('https://your-auth-server.com/.well-known/jwks.json')
)
export async function validateMcpToken(req: NextRequest) {
const authHeader = req.headers.get('authorization')
if (!authHeader?.startsWith('Bearer ')) {
return { error: 'missing_token', status: 401 }
}
const token = authHeader.slice(7)
try {
const { payload } = await jwtVerify(token, JWKS, {
issuer: 'https://your-auth-server.com',
audience: 'mcp-server',
})
return {
clientId: payload.sub as string,
scopes: (payload.scope as string)?.split(' ') ?? [],
}
} catch {
return { error: 'invalid_token', status: 401 }
}
}
El endpoint del servidor MCP llama al middleware antes de entregar el contexto al handler:
export async function POST(req: NextRequest) {
const auth = await validateMcpToken(req)
if ('error' in auth) {
return Response.json(
{ error: auth.error },
{ status: auth.status }
)
}
// auth.clientId y auth.scopes disponibles para el handler
const tools = getToolsForScopes(auth.scopes)
return handleMcpRequest(req, { tools, clientId: auth.clientId })
}
Scopes mapeados a herramientas
Los scopes en el token determinan qué herramientas ve cada cliente. El mapeo es explícito:
const SCOPE_TOOL_MAP: Record<string, string[]> = {
'tools:read': ['get_order', 'get_customer', 'list_products'],
'tools:write': ['create_order', 'update_customer'],
'tools:admin': ['delete_record', 'issue_refund', 'export_data'],
}
function getToolsForScopes(scopes: string[]): string[] {
return [...new Set(scopes.flatMap(s => SCOPE_TOOL_MAP[s] ?? []))]
}
Un cliente con scope: "tools:read" recibe exactamente tres herramientas. Si el agente intenta llamar a issue_refund(), el servidor devuelve un error antes de ejecutar nada. No depende del prompt, no depende del modelo: es una restricción en el handler.
Token refresh: lo que se rompe sin él
El access token caduca. Por defecto, el flujo OAuth 2.0 devuelve un refresh_token junto al access token. El cliente MCP tiene que implementar la renovación automática antes de que el token expire, o las llamadas empezarán a fallar con 401 en medio de una sesión de agente.
El problema es que la mayoría de implementaciones no gestionan el refresh. El token caduca, el agente recibe un error que no sabe interpretar, y el flujo se rompe de forma silenciosa —exactamente el tipo de fallo difícil de diagnosticar en producción que cubrimos en observabilidad de agentes IA.
El patrón correcto es interceptar el 401 en el cliente MCP y renovar antes de reintentar:
async function callMcpTool(tool: string, params: unknown) {
let token = await getStoredToken()
const res = await fetch('/mcp', {
method: 'POST',
headers: { Authorization: `Bearer ${token.access_token}` },
body: JSON.stringify({ tool, params }),
})
if (res.status === 401 && token.refresh_token) {
token = await refreshAccessToken(token.refresh_token)
await storeToken(token)
return callMcpTool(tool, params) // un solo reintento
}
return res.json()
}
Lo que falla cuando lo implementas tú solo
La especificación OAuth 2.0 tiene 70 páginas. Los edge cases que se descubren en producción son predecibles pero no triviales:
- Clock skew entre el servidor de auth y el servidor MCP: el token parece expirado aunque tenga 2 minutos de vida. Se resuelve con
clockToleranceen la validación JWT. - PKCE en clientes móviles: el code verifier tiene que sobrevivir redirecciones que pueden matar el estado de la app.
- Revocación de tokens en tiempo real: si un usuario cierra sesión, el access token sigue siendo válido hasta que caduca. Necesitas un endpoint de introspección o una lista de tokens revocados en caché.
- Rotación de refresh tokens: cada uso del refresh token debería generar uno nuevo. Si no implementas esto, un refresh token comprometido puede usarse indefinidamente.
Estos problemas no aparecen en local. Aparecen bajo carga real, con múltiples clientes, en entornos donde el tiempo del servidor varía.
Resultados reales
Los equipos que implementan OAuth 2.0 correctamente en sus servidores MCP consiguen tres cosas concretas:
Visibilidad de quién usa qué. Cada llamada a una herramienta lleva el client_id del agente que la ejecutó. El log tiene contexto, el debug tiene punto de partida.
Control de acceso sin modificar el prompt. Los scopes son configuración del Authorization Server, no instrucciones al modelo. Cambiar los permisos de un cliente no requiere modificar ni redesplegar el agente.
Superficie de ataque reducida. Un token comprometido expira. Una credencial comprometida tiene alcance acotado por los scopes. El daño potencial tiene límites definidos.
El coste de posponerlo
La autenticación es el tipo de deuda técnica que parece controlable hasta que no lo es. Un servidor MCP sin auth en producción es tolerable mientras solo lo usan tus propios agentes en un entorno controlado. Deja de ser tolerable el día que conectas un cliente externo, cuando auditoría pide logs de acceso, o cuando un token se filtra.
Implementar OAuth 2.0 en un servidor MCP existente no es complejo, pero tiene partes que llevan tiempo: la gestión del refresh, la rotación de tokens, el manejo de clock skew, el mapeo de scopes a herramientas.
Si ya tienes el servidor funcionando y quieres añadir autenticación sin romper lo que ya funciona, en DAILYMP tenemos el patrón implementado y en producción. En una sesión de trabajo lo valoramos y en una semana puedes tener auth en producción.