Guía de implementación de autenticación de servidor MCP: usando la última especificación

Hace unos días (18 de junio de 2025), el equipo MCP (Model Context Protocol) publicó la última versión de la Especificación MCP (2025-06-18). Esta actualización incluye un cambio clave en la especificación de autenticación. Los Servidores MCP ya no emitirán tokens de acceso como un Servidor de Autorización. En cambio, consumirán tokens de acceso y proveerán recursos como un Servidor de Recursos.

Como uno de los mantenedores de MCP Auth (una librería plug and play de autenticación de servidor MCP), he implementado el soporte para la especificación más reciente de autenticación MCP en este proyecto. Basándome en mi experiencia práctica, te mostraré cómo implementar las características de autenticación para tu Servidor MCP que cumplan con la última especificación.

Este artículo te ayudará a:

• Entender cómo funciona la autenticación MCP bajo la nueva especificación
• Aclarar lo que los Servidores MCP necesitan implementar como Servidores de Recursos según los requisitos de la especificación
• Proporcionar una guía para implementar soporte de autenticación que cumpla con los requerimientos más recientes de la especificación en tu Servidor MCP
• Identificar puntos pasados por alto y problemas de seguridad al implementar la especificación MCP auth

Por favor ten en cuenta que este artículo:

• Asume que los lectores tienen conocimientos básicos de JWT (JSON Web Token). El artículo no cubre en detalle la estructura JWT, verificación de firma y otros conceptos básicos. Para detalles específicos, consulta Auth Wiki - JWT
• No introduce en profundidad los varios RFC de los que depende la especificación de autenticación MCP. Solamente ofrece implementaciones que cumplen con estos requerimientos RFC
• No cubre detalles de implementación ni interacción de MCP Client y Authorization. Usualmente estos son implementados por clientes LLM y proveedores de servidor de autorización que soportan MCP basados en sus especificaciones. Los desarrolladores de servidor MCP no necesitan y no pueden interferir en esas implementaciones. Para detalles específicos, consulta OAuth Client y Authorization Server
• Todos los tokens de acceso mencionados en el artículo se asume que son JWT, que es el formato más usado en el mercado. Otras formas de tokens deben usarse según la documentación del proveedor de servidor de autorización correspondiente.

¿Cómo funciona la autenticación MCP?#

De acuerdo con la última especificación de autenticación MCP, el flujo de autentificación MCP se muestra en el siguiente diagrama:

1. El Cliente MCP solicita recursos al Servidor MCP en https://github-tools.com. Como el usuario aún no ha iniciado sesión, la cabecera de autorización HTTP de esta solicitud no contiene un token de acceso que represente al usuario.

2. El Servidor MCP no puede obtener un token de acceso de la cabecera de autorización de la solicitud del Cliente MCP. Retorna un error HTTP 401 al Cliente MCP. Esta respuesta de error incluye una cabecera WWW-Authenticate, que contiene la URL de los metadatos de recursos del Servidor MCP (el valor del campo resource_metadata).

3. El Cliente MCP extrae el valor de resource_metadata del header WWW-Authenticate retornado (por ejemplo: https://github-tools.com/.well-known/oauth-protected-resource). Luego el Cliente MCP solicita los metadatos de los recursos provistos por el Servidor MCP como Servidor de Recursos desde esta dirección. Estos metadatos incluyen contenido como authorization_servers y scopes_supported, ayudando al Cliente MCP a entender cómo obtener el token de acceso necesario para acceder al Servidor MCP y de qué servidor de autorización obtener un token con ciertos permisos.

4-8. El Cliente MCP solicita los metadatos del servidor de autorización basándose en la URL de metadatos del servidor de autorización obtenida de los metadatos del recurso. Luego el Cliente realiza un flujo OAuth 2.1 de autorización con el servidor de autorización y obtiene un token de acceso tras completar la autorización.

9. El Cliente MCP utiliza el token de acceso obtenido del servidor de autorización y realiza otra solicitud de recurso al Servidor MCP.

10. El Servidor MCP retorna el recurso solicitado tras verificar que el token es válido. Desde ese punto, la comunicación entre el Cliente MCP y el Servidor MCP continúa con el token válido.

A continuación, explicaremos cómo implementar el mecanismo de autenticación del servidor MCP paso a paso basado en este flujo de trabajo.

Manejar solicitudes no autorizadas: retornar error 401 y cabecera WWW-Authenticate#

Como se muestra en el flujo anterior, cuando el Cliente MCP envía una solicitud sin un token de acceso al Servidor MCP, este retornará un error HTTP 401 No autorizado con una cabecera WWW-Authenticate que contiene la URL para obtener los metadatos de recurso del Servidor MCP.

Según los requisitos de manejo de errores de autenticación MCP, además de cuando el Cliente MCP no envía token, cuando el Servidor MCP recibe un token inválido, también debe retornar un 401 con cabecera WWW-Authenticate.

Ahora que sabes cuándo retornar un 401, ¿cómo construir la cabecera WWW-Authenticate?

Siguiendo la Sección 5.1 de RFC9728, la cabecera WWW-Authenticate debe incluir el parámetro resource_metadata para indicar la URL de los metadatos del recurso protegido.

Su formato básico es:

Aquí, Bearer es el esquema de autenticación, indicando que se requiere un token bearer para acceder a los recursos protegidos por OAuth 2.0 (ver: documentación MDN). El valor del parámetro resource_metadata que sigue es la URL completa del endpoint de metadatos de recurso provisto por tu Servidor MCP.

La implementación del código es similar a:

Cuando el Cliente MCP recibe este error 401, accederá a los metadatos del recurso del Servidor MCP usando el valor de resource_metadata en la cabecera WWW-Authenticate. Entonces, según la información que provean los metadatos, iniciará una solicitud de autorización al servidor de autorización especificado para obtener un token válido.

Ahora sabemos cuándo retornar 401 y que debemos retornar una URL de resource_metadata, pero todavía falta saber cómo construir esta URL y qué deben contener los metadatos. Eso es lo que presentaremos a continuación.

Implementar mecanismo de descubrimiento de metadatos de recursos#

De acuerdo al flujo de autenticación MCP, después de recibir el 401, el Cliente MCP solicita inmediatamente los metadatos del recurso al Servidor MCP. Por eso, el Servidor MCP, como Servidor de Recursos, debe implementar este mecanismo de descubrimiento.

Determinar la ruta URL del endpoint de metadatos#

En el sistema OAuth, usamos URLs para identificar direcciones de recursos. Esta dirección se llama “indicador de recurso”. Según RFC9728, los metadatos deben alojarse bajo un path específico de /.well-known.

Si tu Servidor MCP (como https://github-tools.com) sólo ofrece un servicio, el endpoint de metadatos debe ser:

Si ofreces varios servicios diferentes en un solo host, cada servicio debe tener un endpoint de metadatos independiente. Por ejemplo, la plataforma empresarial https://api.acme-corp.com ofrece los siguientes servicios:

• https://api.acme-corp.com/github - Servicio de integración con GitHub
• https://api.acme-corp.com/slack - Servicio de integración con Slack
• https://api.acme-corp.com/database - Servicio de consulta de base de datos

Los endpoints correspondientes serían:

• https://api.acme-corp.com/.well-known/oauth-protected-resource/github
• https://api.acme-corp.com/.well-known/oauth-protected-resource/slack
• https://api.acme-corp.com/.well-known/oauth-protected-resource/database

La ventaja de este diseño es que cada servicio puede tener ámbitos de permisos y configuraciones de servidores de autorización diferentes. Por ejemplo:

• El servicio de GitHub usa el servidor OAuth de GitHub y necesita permisos github:read, github:write
• El de Slack usa el OAuth de Slack y requiere slack:channels:read, slack:messages:write
• El servicio de base de datos usa un servidor interno y requiere permiso db:query

De todo lo anterior, resumimos que los endpoints de metadatos siguen el patrón:

Podemos obtener la URL del endpoint de este recurso así:

Construir la respuesta de metadatos de recurso#

Tras definir la ruta, necesitamos que este endpoint retorne metadatos en JSON que cumplan con RFC9728.

En la implementación, debemos centrarnos en cuatro campos principales.

Primero el campo resource, que es el identificador y debe coincidir con la dirección de recurso que el Cliente MCP intenta acceder.

Luego, el campo authorization_servers, que es un array que especifica de qué servidores de autorización el cliente debe solicitar tokens de acceso. Según OAuth 2.0 Protected Resource Metadata (RFC 9728), este campo es opcional, pero en el spec MCP es obligatorio porque el cliente debe saber exactamente a qué servidor pedir autorización. Sin esto, el cliente no podrá completar el flujo de OAuth.

Después tenemos scopes_supported, que lista todos los ámbitos de permisos soportados por este Servidor de Recursos.

Finalmente, el campo bearer_methods_supported, que indica qué métodos soporta el servidor para recibir tokens de acceso. Normalmente se define como ["header"], indicando que el Cliente MCP debe enviar el token vía la cabecera Authorization de HTTP.

Veamos un ejemplo. Supón que configuramos los metadatos para el Servidor MCP https://github-tools.com:

Esto dice al Cliente MCP: quiere acceder a https://github-tools.com, necesita solicitar el token en https://auth.github-tools.com, puede pedir permisos como github:read, github:write, repo:admin, y debe pasar el token vía la cabecera HTTP Authorization.

En la mayoría de casos, configurando estos cuatro campos básicos es suficiente para que el Cliente MCP funcione normalmente. Si necesitas configuraciones más complejas, mira el listado completo de campos en RFC9728.

Validar tokens de acceso#

Después de conseguir el token, el Cliente MCP lo utiliza para acceder al Servidor MCP.

En la práctica, los servidores MCP deben considerar lo siguiente al validar tokens:

1. Al validar el token, realiza la validación basándote en la configuración de tu servidor MCP, no en la información que porta el token sobre el servidor de autorización.
2. Valida que la audiencia (audience) del token sea tu Servidor MCP, garantizando que el token fue emitido para acceder a los recursos de tu servidor.
3. Gestiona correctamente la validación de los ámbitos (scopes)

Usa la configuración del Servidor MCP para validar tokens#

Cuando el Servidor MCP recibe un token, dado que este token contiene información sobre el servidor de autorización (issuer), algunos desarrolladores obtienen los datos necesarios para validar el token a partir del issuer del propio token. Esto es especialmente común si los metadatos de recursos del servidor MCP indican varios servidores de autorización, por ejemplo:

En ese caso, los desarrolladores extraen el issuer del token sin validar y lo usan para encontrar los datos de verificación. Los atacantes pueden construir un servidor de autorización malicioso y emitir un token falso. Si el desarrollador usa ese issuer del token falso (apuntando al servidor falso) y confía en el servidor atacante para validar el token, la validación pasará.

Por eso la validación correcta es:

• Si solo hay un servidor de autorización: valida el token directamente usando la configuración de backend
• Si hay varios: primero extrae el issuer del token sin verificar y busca ese servidor en la lista de configuración del Servidor MCP. Si no se encuentra, rechaza el token

Por supuesto, al validar el token, valida estrictamente el emisor (issuer).

Usando por ejemplo la librería jose de validación JWT:

Validación de audiencia del token#

La sección Token Audience Binding and Validation de la especificación dice que cuando un cliente solicita un token al servidor de autorización, debe especificar para qué servidor de recursos se usará el token. El Servidor MCP debe también verificar que la audiencia (audience) del token es él mismo.

Este mecanismo está basado en el estándar Resource Indicators for OAuth 2.0 (RFC 8707). El flujo es:

1. Fase de solicitud: El Cliente MCP solicita el token al servidor de autorización, especificando el parámetro resource (ejemplo: https://github-tools.com)

2. Fase de emisión: El servidor de autorización asocia ese recurso al token emitido. Para tokens JWT, eso se escribe en el campo audience (aud) del payload.

3. Fase de validación: El Servidor MCP debe comprobar que el campo audience del JWT coincide exactamente con su recurso

Por ejemplo, para el server https://github-tools.com:

Esta validación es clave para evitar abuso de tokens. Sin ella, los atacantes pueden usar tokens de otros servicios para intentar acceder a tu Servidor MCP. Si no validas audience, podrías aceptar tokens que no debieras.

Validación de ámbitos (scopes)#

Algunos Servidores MCP gestionan permisos internos de sus recursos pues distintos usuarios pueden tener ámbitos distintos.

Así que al validar el token, también debes comprobar que el claim scope del token incluye los permisos para acceder al recurso en cuestión:

Ten en cuenta que, según la especificación MCP, si el token no contiene la scope requerida, se debe devolver 403 Forbidden.

Conclusión#

Tras la explicación de este artículo debes poder implementar funciones de autenticación conformes con la especificación más reciente para tu Servidor MCP. Recuerda: valida los tokens de forma segura, configura los metadatos correctamente y verifica estrictamente la audiencia.

Si estás construyendo un Servidor MCP, prueba la librería MCP Auth. Ya implementa todo lo discutido en este artículo y te puede ayudar a integrar autenticación rápidamente.

No dudes en debatir cualquier duda en GitHub. Trabajemos juntos para impulsar el ecosistema MCP.