OAuth Redirect URL: Missing in Docs?

[bene-we]

Hey @danny-avila , first of all huge thanks to your contributions to LibreChat! This helps us a lot in moving forward quickly.

While working with the Spotify MCP example, we ran into some unclear points:

1. registeredClients is set in the code but never actually used anywhere else. Could you clarify its intended purpose and how/where it should be consumed? Right now, we worked around this by not using Dynamic Client Registration (and setting the OAuth settings in librechat.yaml)
2. The redirect URL pattern "/api/mcp//oauth/callback" from Authentication Server back to LibreChat does not seem to be documented anywhere, we had to debug it locally from the Spotify example to get OAuth working with LibreChat. Can you confirm if this is the intended callback path? If yes and you can help me spot the correct location, I can create a PR for the docs
3. Following point 2, we are redirected into LibreChat successfully and access_token / refresh_token are being stored successfully in the DB. Still, our MCP does not receive the access_token and does not seem to store it, I wasn't able to to spot how this works in the Spotify MCP. Could you give me a hint to work this out as well?

Right now, we connected LibreChat directly to the Authentication Server (not through the MCP):

mcpServers:
  sf-mcp:
      type: "streamable-http"
      url: "https://mcp.example.com/mcp"
      headers:
        X-User-ID: "{{LIBRECHAT_USER_ID}}"
      startup: true
      oauth:
        authorization_url: https://oauth-provider.example.com/services/oauth2/authorize
        token_url: https://oauth-provider.example.com/services/oauth2/token
  
        client_id: <clientId>
        client_secret: <clientSecret>
  
        redirect_uri: "https://librechat.example.com/api/mcp/sf-mcp/oauth/callback"
        scope: "api refresh_token"

This flow works until we are redirected to LibreChat, afterwards Prompts to the MCP fail due to missing authorisation (point 3 mentioned above). We previously tried to set respective MCP endpoints in this config and route everything through the MCP (like in the spotify example), which we couldn't get to work because we couldn't get the access_token from the MCP back to LibreChat.

Thanks in advance!

[danny-avila]

@bene-we The Spotify MCP example uses Authorization Server Discovery (https://modelcontextprotocol.io/specification/draft/basic/authorization#authorization-server-discovery), which is the recommended pattern for MCP OAuth integration.

The key points:

1. Dynamic Client Registration is preferred: Instead of hardcoding OAuth settings in librechat.yaml, the MCP server should publish its authorization requirements via Protected Resource Metadata (RFC 9728). This allows clients to automatically discover and register with the authorization server.

2. The registeredClients field: This appears to be for authorization servers that DON'T support Dynamic Client Registration. In such cases, pre-registered client credentials would be needed. Since you're using static OAuth config in librechat.yaml, you're essentially bypassing this dynamic discovery flow.

3. Callback URL pattern: The /api/mcp/<mcp-name>/oauth/callback pattern is correct. This should be documented in the LibreChat MCP integration docs.

4. Token delivery to MCP: In the proper discovery flow:

   • LibreChat acts as the OAuth client
   • After obtaining the access token, LibreChat should include it in the Authorization: Bearer <token> header for all subsequent requests to the MCP server
   • The MCP server validates this token but should NOT pass it through to downstream APIs

Your current setup bypasses the discovery mechanism by hardcoding the OAuth endpoints. While this works, the recommended approach would be:

1. MCP server implements Protected Resource Metadata at /.well-known/oauth-protected-resource
2. LibreChat discovers the authorization server from this metadata
3. LibreChat dynamically registers as a client (if supported)
4. OAuth flow proceeds with discovered/registered credentials

The token not reaching your MCP server suggests LibreChat might not be including the Authorization header in its requests to the MCP after OAuth completion.

The Spotify example was adapted from this article, in case it can provide more information:
https://stytch.com/blog/building-an-mcp-server-oauth-cloudflare-workers/

[bene-we]

@danny-avila thanks for taking the time to respond in such detail, and my apologies for getting back to you that late. I understand the DCR part now, and finally took the time to document the callback URL in #471

One question remains upon your answer, regarding the access token:

The MCP server validates this token but should NOT pass it through to downstream APIs

How should the MCP server access resources in that case? As we've implemented the flow right now:

LibreChat handles the initial OAuth flow, fetches and stores access & refresh token > adds valid token in HTTP header when sending requests to the MCP server > MCP validates token against authorization server > uses token to fetch resources from the connected server.