MCP OAuth Architecture Questions

[nhtruong]

Hi! I've been reviewing the MCP connection management code and have some questions about the design
decisions. Looking for clarification on the intended behavior and potential simplifications.

1. App-Level OAuth Token Logic

Current behavior: App-level connections go through complex OAuth token retrieval but then immediately skip OAuth and fail at startup.

Questions:

• Is the token logic legacy from when app connections supported service accounts or headless OAuth?
• Are there scenarios where app-level connections should actually use stored tokens?
• If not, can we remove the token retrieval logic for app connections entirely?

2. OAuth Discovery via Failure

Current behavior: The system discovers OAuth requirements by attempting connections and using
failures as a side effect to populate oauthServers set.

Questions:

• Would a simple requiresOAuth: true config flag be cleaner than probing via failed connections?
• Are there dynamic OAuth discovery needs that a static config couldn't handle?

3. startup: false Configuration

Current behavior: Servers with startup: false are skipped entirely, which means they bypass OAuth
discovery.

Questions:

• What's the intended use case for startup: false?
• This creates inconsistent OAuth detection - skipped servers won't be in oauthServers set
• Should the UI handle OAuth requirements for servers that weren't probed at startup?

Proposed Simplification

// Instead of complex probing, explicit config:
mcpServers: {
  "github": {
    url: "...",
    requiresOAuth: true,    // Explicit instead of discovered
    startup: false          // Remove this. ALL servers configs will be loaded into memory.
  }
}

This would:

• Eliminate complex token logic for app connections
• Remove OAuth failure probing
• Provide consistent OAuth detection regardless of startup behavior
• Make the system more predictable and maintainable

Thoughts on this approach? Happy to discuss implementation details if this direction makes sense.

[dustinhealy]

Hi Theo,

First of all, thanks for your cogent review of the code; I'm looking forward to collaborating with you on this. A lot of what you touched on in this post is the result of an iterative development cycle during the process of implementing support for the new UI components concerning MCP management, so coming back to it now with a more retrospective view of requirements is probably wise.

I'll do my best here to help explain the thought process behind the current implementation and address each of your points, but at a glance I believe your suggestions seem reasonable and could potentially help clear up the current state of the startup logs for MCP initialization, which have gotten messy and perhaps even misleading in this process.

App-Level OAuth Token Logic

Is the token logic legacy from when app connections supported service accounts or headless OAuth?
Are there scenarios where app-level connections should actually use stored tokens?
If not, can we remove the token retrieval logic for app connections entirely?

Your first prediction is correct; originally OAuth was handled in the console during startup, however now that it is handled in the UI, we opted to skip all detected OAuth flows at startup, with the reasoning being that OAuth connections will currently always be scoped at the user level, rather than app level. However, I know Danny has been working on granular permissions and RBAC, so I would hold off on deciding whether removal of the token retrieval logic is justified until after those changes, since I can foresee a scenario in which there might be higher level OAuth for something like a group-scoped MCP server.

OAuth Discovery via Failure

Would a simple requiresOAuth: true config flag be cleaner than probing via failed connections?
Are there dynamic OAuth discovery needs that a static config couldn't handle?

Certainly from an implementation perspective, relying on explicit configuration for OAuth flagging would reduce code complexity since we would be able to remove the entirety of the discovery mechanism. I had considered this approach myself when implementing the startup: false logic. However, this does place a slightly higher burden on the user, and introduces a new vector for fallibility in the configuration process which automatic discovery currently avoids, so there are considerations to be made before moving forward with refactoring to use the requiresOAuth flag. As for your second question, I am unaware of any dynamic OAuth discovery needs that would not be resolved by a static configuration approach, but that does not preclude their existence, so I will defer to Danny on this one.

startup: false Configuration

What's the intended use case for startup: false?
This creates inconsistent OAuth detection - skipped servers won't be in oauthServers set
Should the UI handle OAuth requirements for servers that weren't probed at startup?

The startup: false flag stems from discussion #8343, wherein support for PAT-based authentication for the github-mcp server was raised as an issue:

github-mcp:
    type: streamable-http
    url: "https://api.githubcopilot.com/mcp/"
    headers:
      Authorization: "{{PAT_TOKEN}}"
    customUserVars:
      PAT_TOKEN:
        title: "GitHub PAT Token"
        description: "GitHub Personal Access Token"

The issue at hand was that github-mcp required a user-defined PAT_TOKEN, which would be supplied post-startup from within the CustomUserVarsSection component (though at the time of implementation I believe it was in MCPConfigDialog and MCPPanel), and so any attempts to connect would always fail at app-level initialization due to lack of authorization.

If we were to eliminate this flag, impact would be minimal (a single failed connection at startup which could be reinitialized from within the UI). However I would suggest keeping this flag (especially if we move forward with explicit configuration via the requiresOAuth flag, since that will resolve the inconsistent OAuth detection in this case), or refactoring with a more tightly scoped naming of the flag to represent the fact that the connection is not app-level and should not be initialized at startup while still differentiating it from an OAuth server in some way.

For your second and third questions, if we were to keep discoverability, I see the inconsistent discovery as a non-issue since, to my knowledge, these flags are used in separate non-overlapping authentication flows, and should not interfere with one another in a normal configuration (i.e. there is no configuration in which a server would both have a startup flag and be an OAuth server).

Hopefully this helps explain the current state of MCPs a bit more.
Thanks again for your efforts and feel free to reach out for further clarification.

[danny-avila]

I just want to add that OAuth discovery is what the MCP inspector does and we try to follow the patterns there.

I believe this is aligned with MCP spec: authorization is optional, but when auth is provided, discovery must be implemented.

• https://modelcontextprotocol.io/specification/draft/basic/authorization#authorization-server-discovery

While a requiresOAuth flag might seem simpler, OAuth discovery provides several advantages over static configuration:

• Servers can change their auth requirements without config updates
• Discovery reveals actual OAuth endpoints and capabilities (PKCE support, etc.)
• It follows established OAuth patterns that developers already know

For the startup: false issue, we could still perform OAuth discovery during config validation without actually connecting to the server.

Also, having a requiresOAuth flag may not be appropriate when the admin/user may be unaware if OAuth is required or not. Since MCP spec requires discovery when auth is used, we should assume MCP servers will implement it according to spec.

[nhtruong]

Thanks for the explanations. I'll keep these business decisions in mind while overhauling the MCP manager for lazy loading and addressing some inconsistency issues.

[nhtruong]

@danny-avila @dustinhealy I'm working on overhauling the MCPManager class and found a few bugs that I've fixed myself. It will also make it easier to add something like Group level connections in the future!!! It's almost done (still need to add tests and test it locally) and I'll have a draft out later today. There are still a few things I need to verify:

This is my understanding of the INTENDED business logic:

1. MCP Servers that do not require authentication (be that OAuth or PAT) are considered app-level
2. App-level connections are reused and shared by all users

However from what I see in the codebase and from our own logs, the app-level connections are actually NEVER used. When a MCP tool is used, MCPManager.callTool() is used. It determines the connection levels by whether a userId is provided or not:

LibreChat/packages/api/src/mcp/manager.ts

Lines 881 to 884 in 74d8a38

	if (userId && user) {
	this.updateUserLastActivity(userId);
	/** Get or create user-specific connection */
	connection = await this.getUserConnection({

But since the user param is always provided, the app-connection is never called even though it exists, and a user-level connection is created instead. If this is a bug, I can easily fix it in my PR. If it's not, then what is the purpose of MCPManager.connections and app-level connections in general?

This also leads to very interesting user experience from reinitialize and status routes. Here's how the routes behave currently:

• The reinitialize route, given a serverName, disconnects the app-level connection with that name and removes that server from MCPManager.connections. It will then creates a user-level connection.
  • This basically turns an app-level connection into a user-level connection ONLY for the user who triggered this route as a side effect.
  • if we ever call the callTool function without the user param for this server afterward, it will encounter an error.
• The status route returns the connection the statuses of all servers, both app- and user-level connections. For each serverName, if app connection exists, it will reports the app-level status. If not, it report the user-level connection status if it exists for that user. If a connection of neither level exists, it reports that server as "disconnected".

So, with the fact that all connections called are actually user-level connections, and let's say we have an MCP server w/o auth called Server_A, here's what our users are experiencing:

• During startup, a connection for the server is added to MCPManager.connections as it is considered an app-level connection. All users will see both of these servers as connected through the status route.
• When we lost connection to Server_A, this server will be grayed out for all users, and ANY USER can click on the reconnect button for this APP-LEVEL connection. Do note that even though this connection is displayed as severed, the users can still use tools from this MCP server without issues since callTool never uses this severed connection anyway.
• When User_B clicks on the reconnect button for Server_A, due to how reinitialize route behaves, the users are starting to see different statuses for Server_A:
  • The status route now returns the user-level connection status for User_B: "connected". After 15 minutes, if User_B doesn't use any MCP tools of any servers, not just Server_A, the status is flipped to "disconnected" due to user-level connection's idle check.
  • All other users (without their own user-level connections and with app-level connection removed by User_B), always see the fallback status of "disconnected" for Server_A.

We have visually confirmed this behavior on our end, and I believe this is not intended. It seems to stem from the complex nature of the connection management logic and the large amount of tech debts we're facing. The overhaul of the MCPManager portion of LC will address most of these issues on the backend and make it easier to add more features on top of this in the future without causing more confusion.

P/S: I notice that both of the routes above makes calls to the loadCustomConfig function, which reads and parses librechat.yaml, even though this config is already cashed during startup and the cache can be retrieved with getCustomConfig. I always assumed loadCustomConfig would always return the same result throughout a deployment since librechat.yaml never changes. If so, I think we should not expose loadCustomConfig to prevent devs from using this expensive IO function.

[nhtruong]

Here's the Draft PR I mentioned. This is a very big change so please take your time to review it. I totally recommend going through the detailed PR description to understand what's going on before reviewing the code itself (I wrote that long wall of text myself, not AI 😛 )

[ronak21691]

@nhtruong I have moved the discussion here, do not want to piss off the reviewers :)

thanks for the response.
I did used the merged code which enables OAuth2.1
But have not able to make it work per user, I have raised the issue here, you can see the implementation details as well - taylorwilsdon/google_workspace_mcp#162

I just want to run a OAuth enabled MCP server for my internal team so that I can add more MCP servers, I am tired of trying multiple things and not able to make this work.

Some pointers will definitely help. Thanks

This huge pr taylorwilsdon/google_workspace_mcp#137 supposedly fix the issue, I didn't test it ( merged only last week ) but you have to define MCP_ENABLE_OAUTH21 and use http-streamable protocol . It should work with LC. Note that LC's management of access_token and refresh_token is significantly more secure than what does google_workspace_mcp as LC does encrypt them before storing them in the database.

[nhtruong]

I think you meant to tag @owengo here as well :)

[nhtruong]

I'm closing this discussion because the issues has been resolved.

@ronak21691 I see that your discussion went on in that PR instead. If it's still an issue, you should create a new discussion :)