𝗧𝗵𝗲 𝗢𝗽𝗲𝗻𝗜𝗗 𝗖𝗼𝗻𝗳𝗶𝗴𝘂𝗿𝗮𝘁𝗶𝗼𝗻 𝗙𝗶𝘅 𝗙𝗼𝗿 𝗠𝗖𝗣 𝗖𝗼𝗻𝗻𝗲𝗰𝘁𝗼𝗿𝘀

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:

  1. 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.

  2. 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.

L'alias di configurazione OpenID "well-known" che fa funzionare i connettori MCP senza complicazioni

Il Model Context Protocol (MCP) è un nuovo standard aperto che consente agli sviluppatori di creare connessioni sicure e bidirezionali tra le proprie fonti di dati e i modelli di IA. Man mano che sempre più sviluppatori adottano MCP, la necessità di meccanismi di autenticazione robusti diventa sempre più critica.

Una sfida comune nella creazione di connettori MCP è la configurazione dell'autenticazione. Molti servizi utilizzano OAuth2 o OpenID Connect (OIDC), il che richiede diversi endpoint differenti:

  • authorization_endpoint
  • token_endpoint
  • userinfo_endpoint
  • jwks_uri

Chiedere agli utenti di fornire tutti questi URL offre una scarsa esperienza utente ed è soggetto a errori.

La soluzione è semplice: utilizzare il meccanismo di OpenID Connect Discovery.

La maggior parte dei provider conformi a OIDC ospita un documento di configurazione in una posizione standardizzata: /.well-known/openid-configuration.

Utilizzando questo endpoint "well-known", un connettore MCP ha bisogno di un unico pezzo di informazione da parte dell'utente: l'Issuer URL.

Una volta che il connettore ha l'Issuer URL, può recuperare il documento di configurazione e scoprire automaticamente tutti gli endpoint necessari. Ciò rende il processo di connessione fluido e molto più resiliente ai cambiamenti nella configurazione del provider.

In breve, sfruttando l'alias .well-known/openid-configuration, possiamo far sì che i connettori MCP funzionino senza problemi.