La solución de la configuración de OpenID para los conectores MCP
Esta semana pasé demasiado tiempo arreglando un conector MCP remoto.
El conector no dejaba de fallar al intentar encontrar mi servidor OAuth. El servidor funcionaba correctamente. El problema era una única ruta faltante y una redirección.
Cuando usas OAuth con MCP, esperas que los documentos de descubrimiento funcionen. La mayoría de las herramientas buscan estas dos rutas:
- /.well-known/oauth-authorization-server
- /.well-known/oauth-protected-resource
Estas indican a los clientes dónde encontrar los endpoints de autorización y de tokens.
El problema es que muchos clientes no buscan esas rutas específicas. En su lugar, buscan /.well-known/openid-configuration.
Esta es una ruta de OpenID Connect. Es una especificación diferente, pero reside en el mismo lugar. Mi paquete no registró esta ruta porque sigue la especificación OAuth, no la de OIDC.
El cliente llama a una puerta que no existe. Recibe un error 404 y se detiene.
Tenía dos opciones:
Usar una redirección de proxy inverso en Nginx. Esta es una solución perezosa. Mueve la lógica fuera de tu código y la traslada a tu infraestructura. Es difícil de probar y fácil de romper durante un despliegue.
Corregirlo dentro de la aplicación. Esta es la mejor manera.
Elegí hacer que la aplicación responda a la consulta. Creé un alias que redirige la ruta de OpenID a la ruta de autorización de OAuth.
Utilicé un 308 Permanent Redirect.
Una redirección 302 puede cambiar una solicitud POST en una solicitud GET. Una redirección 308 es estricta. Le indica al cliente que vaya a la nueva URL y mantenga el mismo método y cuerpo. Esta es la forma correcta de gestionar un traslado permanente.
También puse esto detrás de un flag de configuración. Esto permite a los usuarios desactivarlo si ejecutan su propio descubrimiento OIDC.
Al hacer esto en el código, puedo escribir pruebas:
- Una prueba comprueba si la redirección ocurre correctamente.
- Una prueba sigue la redirección para asegurar que los metadatos sean válidos.
Esto garantiza que, si la estructura de los metadatos cambia, mis pruebas fallen inmediatamente. Encuentro el error en mi pipeline en lugar de encontrarlo cuando un usuario no puede conectarse.
Las especificaciones suelen diferir en la práctica. Incluso cuando dos estándares comparten objetivos similares, los clientes elegirán rutas diferentes. Como desarrollador de servidores, deberías responder a ambas puertas.
Dirígelos a la misma habitación, utiliza el código de redirección correcto y respalda todo con pruebas.