¿Por qué PKCE para MCP cuando los agentes no son navegadores?

PKCE (Clave de prueba para intercambio de códigos) vincula el código de autorización a un secreto criptográfico único que solo el cliente iniciador conoce. En el contexto de MCP, el atacante no es una extensión de navegador maliciosa; es un agente deshonesto o un código de autorización robado que flota en el registro de una terminal. PKCE significa que un código interceptado no se puede canjear sin el verificador del código original. OAuth 2.1 requiere PKCE para cada flujo de código de autorización, incluidos los clientes confidenciales, por lo que MCP simplemente sigue la especificación.

¿Qué es un documento de metadatos de recursos protegidos?

Un documento PRM es un archivo JSON servido en /.well-known/oauth-protected-resource que indica a los clientes de OAuth dónde reside el servidor de autorización, qué alcances acepta el recurso y qué identificador de recurso colocar en la reclamación aud. La especificación de autorización de MCP agregó PRM para que un cliente de MCP descubra su configuración de autenticación sin configuración fuera de banda. El cliente recupera el PRM, sigue la URL de Authorization_servers hasta los metadatos de AS, ejecuta el baile OAuth y llega a su servidor MCP con un token de portador válido.

¿Necesito un registro de cliente dinámico?

Para servidores MCP públicos expuestos a muchos clientes, sí. El registro dinámico de cliente (RFC 7591) permite que un cliente MCP se registre automáticamente en su servidor de autorización, reciba un client_id e inicie el flujo de OAuth en un solo viaje. Sin él, cada usuario tiene que crear manualmente una aplicación en su panel antes de poder conectar Claude o Cursor. Para integraciones internas o incluidas en la lista permitida, un client_id preaprovisionado aún funciona.

¿Dónde vive el token al portador durante la sesión?

En el encabezado de Autorización de cada solicitud de MCP. HTTP transmisible hace que esto sea limpio; cada solicitud lleva el token y su servidor lo verifica en el middleware antes de enviar la llamada a la herramienta. Los tokens de acceso de corta duración (de 5 a 60 minutos) con tokens de actualización en poder del cliente minimizan el radio de explosión de una línea de registro filtrada. Nunca inserte el token en la URL; Los registros y los servidores proxy capturan las URL de forma rutinaria.

¿Cómo se comparan los alcances de las herramientas MCP con los alcances de OAuth?

MCP se basa en la autorización basada en roles: un token tiene alcances como herramientas: lectura, herramientas: invoke: seguro o herramientas: invoke: destructivo, y las anotaciones de herramientas individuales declaran qué alcances requieren. Los ámbitos se asignan uno a uno a los ámbitos de OAuth, por lo que puede utilizar el mismo diseño de alcance que ya tiene para una API REST. La nueva pieza son anotaciones a nivel de herramienta en el lado de MCP; hacen que la decisión de autorización sea visible en el registro de la herramienta, no solo en el código del controlador.

Tutorial

MCP OAuth 2.1 con PKCE: proteja el servidor de su agente en 7 pasos

15 abr 2026 | 9 min read

La especificación MCP 2026-03-15 convierte a OAuth 2.1 + PKCE en el estándar de autorización para servidores de agentes. Siete pasos para realizar el envío: metadatos de PRM, registro dinámico de clientes, diseño de alcance y validación de tokens con código.

Padlock representing OAuth 2.1 authorization for MCP servers — Photo by FLY:D on Unsplash

La especificación MCP 2026-03-15 bloquea OAuth 2.1 con PKCE como estándar de autorización para servidores MCP remotos. Las claves API en las variables de entorno todavía funcionan desde el primer día, pero el registro, Claude Desktop, Cursor, VS Code Copilot y Windsurf prefieren servidores respaldados por OAuth cuando los usuarios busque integraciones. Si su servidor aún solicita un portador de larga duración en un archivo de configuración, están dejando una parte de la distribución sobre la mesa.

La parte difícil no es OAuth en sí; son las cinco pequeñas especificaciones que compone el flujo de autenticación de MCP juntos: OAuth 2.1 (RFC 9700), PKCE (RFC 7636), Registro de cliente dinámico (RFC 7591), Indicadores de recursos (RFC 8707) y metadatos de recursos protegidos. Cada uno es pequeño; el cableado es donde los equipos se atascan. Aquí está el camino, en orden.

Paso 1: entregar un documento de metadatos de recursos protegidos

El archivo PRM les dice a los clientes dónde está su servidor de autorización, qué alcances acepta y qué identificador de recurso para poner en el aud afirmar. Anótalo en /.well-known/oauth-protected-resource en el mismo origen que su punto final MCP:

La authorization_servers La lista es el salto de descubrimiento. Los clientes van a buscar su PRM, siga la primera entrada del documento de metadatos de AS y cree la URL de autorización a partir de allí. Mantenga la lista en una sola entrada a menos que dirija una federación; múltiples emisores confunden al cliente y nada en la especificación lo requiere.

Paso 2: publicar los metadatos del servidor de autorización

Su proveedor de identidad (Auth0, Okta, Clerk, Cloudflare Access o Hydra autohospedado) sirve los metadatos de AS en /.well-known/oauth-authorization-server. Los clientes MCP lo consumen para conocer los puntos finales de autorización y token, los tipos de concesión admitidos y la ubicación de JWKS para verificación de token:

Tres campos que exige la especificación: code_challenge_methods_supported debe incluir S256; grant_types_supported debe incluir authorization_code y refresh_token; registration_endpoint debe estar presente si admite clientes dinámicos. extraño a cualquiera y Claude Desktop marcará el servidor como no compatible durante la instalación.

Paso 3: generar un par PKCE en el cliente

PKCE tiene 20 líneas de código de cliente y elimina la clase de interceptación de código de autorización de ataque. Genere 32 bytes aleatorios, codifíquelos en base64url en un verificador, SHA-256 el verificador en un desafío y envíe el desafío con la solicitud de autorización:

La resource El parámetro (RFC 8707) es el que la mayoría de las implementaciones omiten. sin Al hacerlo, un token creado para su servidor MCP se puede reproducir contra cualquier otra API que confíe en el mismo emisor; con ello, el aud el reclamo fija el token en su identificador de recurso y nada más lo acepta.

Paso 4: Cambia el código por tokens

Después de la redirección, el cliente envía el código más el verificador original al token. punto final. El servidor de autorización vuelve a calcular el SHA-256 del verificador y lo compara con el desafío almacenado; si coinciden, obtienes un token de acceso:

Guarde el token de actualización en un almacenamiento seguro (llavero, administrador de credenciales de Windows, Linux libsecret) y elimine el verificador del almacenamiento de la sesión en el momento en que el intercambio sea exitoso. Acceso las fichas viven de 5 a 60 minutos; Los tokens de actualización duran más, pero aún así deberían rotar cuando se usan.

Paso 5: verificar el token de portador en cada solicitud de MCP

Streamable HTTP simplifica la verificación de tokens: cada solicitud HTTP lleva el Authorization encabezado, por lo que su servidor MCP lo verifica en el middleware antes enviar la llamada a la herramienta. Obtenga el JWKS una vez, guárdelo en caché y valide el emisor, la audiencia y Caducidad en cada llamada:

Las tres afirmaciones que detectan errores reales: iss fija al emisor; aud fija el recurso (evita la reproducción entre recursos); exp atrapa fichas obsoletas. No acepte tokens sin estos; "Validé el firma" no es lo mismo que "validé los reclamos".

Paso 6: identifique cada herramienta en los alcances que declaran sus anotaciones

El diseño de alcance menos de OAuth 2.1 le brinda acceso binario: el cliente puede llamar a todas las herramientas o ninguno. El sistema de anotación MCP cierra esa brecha al permitir que cada herramienta declare los alcances que necesidades. El controlador lee las anotaciones y los alcances del token en el momento de la invocación:

Mantenga separados los ámbitos destructivo y de solo lectura. Un usuario que concedió tools:read a ejecutar un informe semanal no debería poder ejecutarse send_email de la misma ficha. Claude Desktop y Cursor muestran los ámbitos solicitados en la pantalla de consentimiento, por lo que la división hace la UX honesta sobre lo que el cliente puede hacer.

Paso 7: Admite el registro dinámico de clientes

El registro dinámico de cliente permite que un cliente MCP se registre automáticamente en su servidor de autorización sin que un humano complete un formulario. Cursor o Claude Desktop envía una solicitud de registro, recibe un client_idy ejecuta el flujo OAuth inmediatamente:

Esta es la pieza que mueve su servidor MCP de "pegar una clave API en un archivo de configuración" a "haga clic en Conectar en el cursor y conceda acceso". Vale la pena el trabajo si su servidor es público; saltable si solo realiza envíos a un pequeño grupo de clientes conocidos.

Verificar el flujo completo de un extremo a otro

Una vez que las piezas están en su lugar, una llamada completa a la herramienta MCP se parece a cualquier otra autenticación de portador. Solicitud HTTP:

si ves 401 con WWW-Authenticate: Bearer resource_metadata="...", el cliente sabe dónde descubrir su configuración de autenticación y volver a ejecutar el flujo. Ese encabezado es el apretón de manos que hace posible la actualización silenciosa del token y la reconexión después de una revocación.

Coloque la URL de PRM en el WWW-Authenticate encabezado en cada respuesta 401. El PCM spec hace que esta sea la pista de descubrimiento canónica; clientes que ven un retroceso 401 sin anotar hasta pedirle al usuario una clave API, que es exactamente el flujo que OAuth 2.1 está tratando de reemplazar.

Hoja de referencia para el diseño del alcance

Alcance	Cubiertas	Subvención predeterminada
`tools:read`	Enumere las herramientas disponibles, lea las descripciones	Siempre concedido con consentimiento
`tools:invoke:safe`	Llamadas a herramientas idempotentes de solo lectura (búsquedas, análisis)	Otorgado por consentimiento del usuario
`tools:invoke:destructive`	Llamadas de herramientas mutantes (enviar correo electrónico, crear pedido)	Requiere consentimiento explícito por sesión
`resources:read`	Acceso de solo lectura a recursos expuestos	Concedido por patrón de recursos
`prompts:read`	Enumerar y leer mensajes definidos por el servidor	Concedida con el consentimiento

Conclusiones clave

OAuth 2.1 requiere PKCE. No es algo agradable de tener; cada flujo de código de autenticación lleva un verificador y desafío o no cumple con las especificaciones.
PRM en /.well-known/oauth-protected-resource es el punto de entrada. Los clientes descubren su configuración de autenticación desde esa URL; omítelo y los clientes no podrán realizar la configuración automática.
Utilice el resource parámetro (RFC 8707). Fija la audiencia simbólica a su servidor MCP para que un token filtrado no pueda reproducirse en otras API.
Validar emisor, audiencia, vencimiento, alcance. Los controles de firma por sí solos permiten reproducción entre recursos.
Dividir alcances destructivos. tools:read, tools:invoke:safe, y tools:invoke:destructive dar a los usuarios la consentimiento UX que esperan de los permisos del sistema operativo.
El registro dinámico del cliente desbloquea instalaciones sin configuración. pagar el costo de implementación una vez; Cada nuevo cliente de MCP se beneficia para siempre.

El servidor MCP alojado de Botoi en api.botoi.com/mcp sigue el mismo patrón. Navega por el Documentos de configuración de MCP para configuraciones de Claude Desktop, Claude Code, Cursor, VS Code y Windsurf. Por la firma de JWT y primitivas de verificación que utiliza el middleware anterior, consulte la Puntos finales de la API JWT en los documentos interactivos.

FAQ

¿Por qué PKCE para MCP cuando los agentes no son navegadores?: PKCE (Clave de prueba para intercambio de códigos) vincula el código de autorización a un secreto criptográfico único que solo el cliente iniciador conoce. En el contexto de MCP, el atacante no es una extensión de navegador maliciosa; es un agente deshonesto o un código de autorización robado que flota en el registro de una terminal. PKCE significa que un código interceptado no se puede canjear sin el verificador del código original. OAuth 2.1 requiere PKCE para cada flujo de código de autorización, incluidos los clientes confidenciales, por lo que MCP simplemente sigue la especificación.
¿Qué es un documento de metadatos de recursos protegidos?: Un documento PRM es un archivo JSON servido en /.well-known/oauth-protected-resource que indica a los clientes de OAuth dónde reside el servidor de autorización, qué alcances acepta el recurso y qué identificador de recurso colocar en la reclamación aud. La especificación de autorización de MCP agregó PRM para que un cliente de MCP descubra su configuración de autenticación sin configuración fuera de banda. El cliente recupera el PRM, sigue la URL de Authorization_servers hasta los metadatos de AS, ejecuta el baile OAuth y llega a su servidor MCP con un token de portador válido.
¿Necesito un registro de cliente dinámico?: Para servidores MCP públicos expuestos a muchos clientes, sí. El registro dinámico de cliente (RFC 7591) permite que un cliente MCP se registre automáticamente en su servidor de autorización, reciba un client_id e inicie el flujo de OAuth en un solo viaje. Sin él, cada usuario tiene que crear manualmente una aplicación en su panel antes de poder conectar Claude o Cursor. Para integraciones internas o incluidas en la lista permitida, un client_id preaprovisionado aún funciona.
¿Dónde vive el token al portador durante la sesión?: En el encabezado de Autorización de cada solicitud de MCP. HTTP transmisible hace que esto sea limpio; cada solicitud lleva el token y su servidor lo verifica en el middleware antes de enviar la llamada a la herramienta. Los tokens de acceso de corta duración (de 5 a 60 minutos) con tokens de actualización en poder del cliente minimizan el radio de explosión de una línea de registro filtrada. Nunca inserte el token en la URL; Los registros y los servidores proxy capturan las URL de forma rutinaria.
¿Cómo se comparan los alcances de las herramientas MCP con los alcances de OAuth?: MCP se basa en la autorización basada en roles: un token tiene alcances como herramientas: lectura, herramientas: invoke: seguro o herramientas: invoke: destructivo, y las anotaciones de herramientas individuales declaran qué alcances requieren. Los ámbitos se asignan uno a uno a los ámbitos de OAuth, por lo que puede utilizar el mismo diseño de alcance que ya tiene para una API REST. La nueva pieza son anotaciones a nivel de herramienta en el lado de MCP; hacen que la decisión de autorización sea visible en el registro de la herramienta, no solo en el código del controlador.

Empieza a construir con botoi

150+ endpoints de API para consultas, procesamiento de texto, generacion de imagenes y utilidades para desarrolladores. Plan gratuito, sin tarjeta de credito.

Ver documentacion de la API Ver todas las herramientas