The OpenID Configuration Fix For MCP Connectors
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.