𝗧𝗵𝗲 𝗢𝗽𝗲𝗻𝗜𝗗 𝗖𝗼𝗻𝗳𝗶𝗴𝘂𝗿𝗮𝘁𝗶𝗼𝗻 𝗙𝗶𝘅 𝗙𝗼𝗿 𝗠𝗖𝗣 𝗖𝗼𝗻𝗻𝗲𝗰𝘁𝗼𝗿𝘀
I spent too much time this week fixing a remote MCP connector.
The connector kept failing to find my OAuth server. The server was working fine. The issue was a single missing route and a redirect.
When you use OAuth with MCP, you expect discovery documents to work. Most tools look for these two paths:
- /.well-known/oauth-authorization-server
- /.well-known/oauth-protected-resource
These tell clients where to find authorization and token endpoints.
The problem is that many clients do not look for those specific paths. Instead, they look for /.well-known/openid-configuration.
This is an OpenID Connect path. It is a different spec, but it lives in the same place. My package did not register this path because it follows the OAuth spec, not the OIDC spec.
The client knocks on a door that does not exist. It gets a 404 error and quits.
I had two choices:
Use a reverse-proxy redirect in Nginx. This is a lazy fix. It moves your logic out of your code and into your infrastructure. It is hard to test and easy to break during a deployment.
Fix it inside the application. This is the better way.
I chose to make the app answer the probe. I created an alias that redirects the OpenID path to the OAuth authorization path.
I used a 308 Permanent Redirect.
A 302 redirect can change a POST request into a GET request. A 308 redirect is strict. It tells the client to go to the new URL and keep the same method and body. This is the correct way to handle a permanent move.
I also put this behind a configuration flag. This allows users to turn it off if they run their own OIDC discovery.
By doing this in the code, I can write tests:
- One test checks if the redirect happens correctly.
- One test follows the redirect to ensure the metadata is valid.
This ensures that if the metadata structure changes, my tests fail immediately. I find the error in my pipeline instead of finding it when a user cannot connect.
Specs often differ in practice. Even when two standards share similar goals, clients will pick different paths. As a server developer, you should answer both doors.
Point them to the same room, use the right redirect code, and back it up with tests.
O alias de configuração OpenID well-known que faz os conectores MCP funcionarem perfeitamente
Se você tem trabalhado com o Model Context Protocol (MCP), sabe que fazer os conectores funcionarem perfeitamente com diferentes provedores de autenticação pode ser uma dor de cabeça.
O ingrediente secreto é um endpoint simples e padronizado: .well-known/openid-configuration.
Este endpoint faz parte da especificação de descoberta do OpenID Connect (OIDC). Ele permite que um cliente (como um conector MCP) descubra automaticamente os endpoints necessários para realizar a autenticação e a autorização sem que o usuário precise configurá-los manualmente.
Em vez de exigir que os usuários insiram manualmente o endpoint de autorização, o endpoint de token, a URI do JWKS e muito mais, o conector MCP precisa apenas da URL do emissor (issuer URL).
Quando o conector recebe a URL do emissor, ele anexa automaticamente /.well-known/openid-configuration a ela e busca o documento JSON.
Isso torna o processo de configuração "zero-config" para o usuário final.
Ao aproveitar este alias well-known, os conectores MCP podem se tornar muito mais "plug-and-play", reduzindo significativamente a barreira de entrada para novas integrações.