🪪 fix: Consolidate MCP OAuth Policy by danny-avila · Pull Request #13254 · LibreChat-AI/LibreChat

danny-avila · 2026-05-22T14:01:31Z

I built on #12759 and folded in the policy-layer fix from #12511 to make MCP OAuth decisions consistent across proactive connection, discovery, and user connection setup. This supersedes #12759 and #12511.

Consolidated MCP OAuth detection around a shared policy: requiresOAuth: false opts out, requiresOAuth: true opts in, and configured oauth opts in when requiresOAuth is unset.
Improved the OAuth UX for MCP servers that need user authorization by prompting before the first protected tool call when no tokens exist, instead of letting the server appear connected and then failing later with a delayed auth error.
Preserved requiresOAuth: false as an explicit escape hatch so private/OIDC pass-through MCP servers do not show unwanted OAuth prompts and continue to fail promptly on normal auth failures.
Refined proactive OAuth so missing tokens start OAuth before connect when the shared policy marks the server as OAuth-enabled.
Updated user-specific MCP connections to derive useOAuth from server config instead of hardcoding OAuth for every user connection.
Added a non-OAuth fallback oauthRequired handler so 401/403 responses from non-OAuth servers fail promptly instead of waiting for OAuth handling timeouts.
Added regression coverage for configured OAuth, explicit opt-out, metadata-only behavior, non-OAuth fallback cleanup, user-connection policy derivation, missing flowManager guards, listener cleanup, missing handlers, and discovery mode continuing to list tools without initiating OAuth.

Change Type

Bug fix (non-breaking change which fixes an issue)

Testing

Ran npx jest src/mcp/__tests__/MCPConnectionFactory.test.ts src/mcp/__tests__/MCPManager.test.ts --runInBand from packages/api.
Ran npx eslint packages/api/src/mcp/MCPConnectionFactory.ts packages/api/src/mcp/UserConnectionManager.ts packages/api/src/mcp/MCPManager.ts packages/api/src/mcp/utils.ts packages/api/src/mcp/types/index.ts packages/api/src/mcp/__tests__/MCPConnectionFactory.test.ts packages/api/src/mcp/__tests__/MCPManager.test.ts.
Ran npm run build:api.
Ran git diff --check.

Test Configuration:

Node.js v20.19.5
npm 10.8.2
Branch based on Implement proactive OAuth flow for connections without tokens #12759 head with 🛂 fix: Respect requiresOAuth Config in User MCP Connections #12511 policy changes folded in, targeting dev

Checklist

My code adheres to this project's style guidelines
I have performed a self-review of my own code
My changes do not introduce new warnings
I have written tests demonstrating that my changes are effective or that my feature works
Local unit tests pass with my changes

… tokens

…ctory Co-authored-by: Copilot <copilot@github.com>

danny-avila · 2026-05-22T14:01:54Z

@codex review

Copilot

Pull request overview

Refines MCP proactive OAuth initiation so OAuth flows are started even when a server allows unauthenticated initialize/tools/list (e.g., Google hosted MCPs), including cases where protected-resource OAuth metadata is present, while preserving requiresOAuth: false as an explicit opt-out. It also adds regression tests to validate the new gating and listener cleanup behavior.

Changes:

Added proactive OAuth initiation before connecting when no stored tokens exist and the server is determined to require OAuth (via requiresOAuth, oauth config, or discovered oauthMetadata), with an explicit requiresOAuth: false escape hatch.
Implemented proactive OAuth event waiting with explicit cleanup of oauthHandled/oauthFailed listeners on success, failure, and timeout.
Added Jest coverage for proactive OAuth triggers (including metadata-driven), explicit-false gating, listener cleanup, and discovery-mode behavior.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
packages/api/src/mcp/MCPConnectionFactory.ts	Adds proactive OAuth gating + pre-connect OAuth initiation with listener cleanup and timeout handling.
packages/api/src/mcp/tests/MCPConnectionFactory.test.ts	Adds regression tests for proactive OAuth behavior, gating rules, listener cleanup, and discovery-mode behavior.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

chatgpt-codex-connector · 2026-05-22T14:07:28Z

Codex Review: Didn't find any major issues. Nice work!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

danny-avila · 2026-05-22T14:10:23Z

@codex review

github-actions · 2026-05-22T14:11:02Z

GitNexus: 🚀 deployed

The LibreChat-pr-13254 index is now live on the MCP server.
Deploy run

chatgpt-codex-connector · 2026-05-22T14:15:46Z

Codex Review: Didn't find any major issues. Already looking forward to the next diff.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

github-actions · 2026-05-22T14:19:01Z

GitNexus: 🚀 deployed

The LibreChat-pr-13254 index is now live on the MCP server.
Deploy run

danny-avila · 2026-05-22T14:31:31Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 55ff945c66

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

danny-avila · 2026-05-22T14:39:43Z

@codex review

chatgpt-codex-connector · 2026-05-22T14:44:59Z

Codex Review: Didn't find any major issues. Keep it up!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

github-actions · 2026-05-22T14:49:03Z

GitNexus: 🚀 deployed

The LibreChat-pr-13254 index is now live on the MCP server.
Deploy run

danny-avila · 2026-05-23T00:15:59Z

@codex review

chatgpt-codex-connector · 2026-05-23T00:22:34Z

Codex Review: Didn't find any major issues. Breezy!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

github-actions · 2026-05-23T00:25:29Z

GitNexus: 🚀 deployed

The LibreChat-pr-13254 index is now live on the MCP server.
Deploy run

danny-avila · 2026-05-23T00:31:15Z

@codex review

chatgpt-codex-connector · 2026-05-23T00:38:31Z

Codex Review: Didn't find any major issues. Bravo.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

* 🦉 feat: Implement proactive OAuth flow for connections without stored tokens * 🤝 fix: Enhance proactive OAuth flow handling in MCPConnectionFactory * fix: Add timeout handling for proactive OAuth flow in MCPConnectionFactory Co-authored-by: Copilot <copilot@github.com> * fix: Refine proactive MCP OAuth flow * test: Cover proactive OAuth missing handler * fix: Require explicit MCP OAuth signal * fix: Consolidate MCP OAuth policy --------- Co-authored-by: Gil Assunção <gil.assuncao@parceiros.nos.pt> Co-authored-by: Copilot <copilot@github.com>

Range: 8310e9a..190cdee Highlights: - Security: MCP OAuth hardening (LibreChat-AI#13264, LibreChat-AI#13274, LibreChat-AI#13276, LibreChat-AI#13254, LibreChat-AI#13256), SSRF guards, system tenant rejection (LibreChat-AI#13278), data retention semantics (LibreChat-AI#13049) - LLM: Gemini 3.5 Flash (LibreChat-AI#13231), Gemini Tool Combinations (LibreChat-AI#13273), AWS Bedrock API key support (LibreChat-AI#8690) [pending removal in stage-1] - Streaming/UI: cache preservation, race fixes, optimistic sidebar (LibreChat-AI#13298) - Observability: Prometheus metrics (LibreChat-AI#13265), OTel SSE tracing (LibreChat-AI#13266), build metadata (LibreChat-AI#12756) - Infra: graceful shutdown (LibreChat-AI#13211), readiness endpoints (LibreChat-AI#13212), Redis cluster safe delete (LibreChat-AI#13275) - CI/format: prettier --write all workspaces (LibreChat-AI#13281), ESLint enforcement (LibreChat-AI#13280) - Deps: @librechat/agents -> v3.1.96

* 🦉 feat: Implement proactive OAuth flow for connections without stored tokens * 🤝 fix: Enhance proactive OAuth flow handling in MCPConnectionFactory * fix: Add timeout handling for proactive OAuth flow in MCPConnectionFactory Co-authored-by: Copilot <copilot@github.com> * fix: Refine proactive MCP OAuth flow * test: Cover proactive OAuth missing handler * fix: Require explicit MCP OAuth signal * fix: Consolidate MCP OAuth policy --------- Co-authored-by: Gil Assunção <gil.assuncao@parceiros.nos.pt> Co-authored-by: Copilot <copilot@github.com>

gafda and others added 4 commits May 20, 2026 10:34

🦉 feat: Implement proactive OAuth flow for connections without stored…

fdd540e

… tokens

🤝 fix: Enhance proactive OAuth flow handling in MCPConnectionFactory

b1349f7

fix: Add timeout handling for proactive OAuth flow in MCPConnectionFa…

78882ec

…ctory Co-authored-by: Copilot <copilot@github.com>

fix: Refine proactive MCP OAuth flow

861ecb4

Copilot AI review requested due to automatic review settings May 22, 2026 14:01

Copilot started reviewing on behalf of danny-avila May 22, 2026 14:01 View session

Copilot AI reviewed May 22, 2026

View reviewed changes

Comment thread packages/api/src/mcp/__tests__/MCPConnectionFactory.test.ts Outdated

test: Cover proactive OAuth missing handler

55ff945

danny-avila mentioned this pull request May 22, 2026

Implement proactive OAuth flow for connections without tokens #12759

Closed

8 tasks

chatgpt-codex-connector Bot reviewed May 22, 2026

View reviewed changes

Comment thread packages/api/src/mcp/MCPConnectionFactory.ts Outdated

fix: Require explicit MCP OAuth signal

cb11253

danny-avila marked this pull request as ready for review May 22, 2026 23:35

fix: Consolidate MCP OAuth policy

a02d9eb

danny-avila changed the title ~~🪪 fix: Refine Proactive MCP OAuth~~ 🪪 fix: Consolidate MCP OAuth Policy May 23, 2026

danny-avila mentioned this pull request May 23, 2026

🛂 fix: Respect requiresOAuth Config in User MCP Connections #12511

Closed

6 tasks

danny-avila merged commit d462bf4 into dev May 23, 2026
11 checks passed

danny-avila deleted the danny-avila/mcp-oauth-proactive-refine branch May 23, 2026 00:43

danny-avila linked an issue May 23, 2026 that may be closed by this pull request

[Bug]: MCP servers that allow unauthenticated initialize (HTTP 200) never trigger OAuth — e.g. Google's hosted Drive MCP #13249

Closed

danny-avila mentioned this pull request May 23, 2026

[Bug]: MCP servers that allow unauthenticated initialize (HTTP 200) never trigger OAuth — e.g. Google's hosted Drive MCP #13249

Closed

danny-avila mentioned this pull request May 27, 2026

🐢 ci: Raise test-packages-api timeout to 20 min #13326

Merged

2 tasks

Uh oh!

Conversation

danny-avila commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Change Type

Testing

Test Configuration:

Checklist

Uh oh!

danny-avila commented May 22, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

chatgpt-codex-connector Bot commented May 22, 2026

Uh oh!

danny-avila commented May 22, 2026

Uh oh!

github-actions Bot commented May 22, 2026

GitNexus: 🚀 deployed

Uh oh!

chatgpt-codex-connector Bot commented May 22, 2026

Uh oh!

github-actions Bot commented May 22, 2026

GitNexus: 🚀 deployed

Uh oh!

danny-avila commented May 22, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

danny-avila commented May 22, 2026

Uh oh!

chatgpt-codex-connector Bot commented May 22, 2026

Uh oh!

github-actions Bot commented May 22, 2026

GitNexus: 🚀 deployed

Uh oh!

danny-avila commented May 23, 2026

Uh oh!

chatgpt-codex-connector Bot commented May 23, 2026

Uh oh!

github-actions Bot commented May 23, 2026

GitNexus: 🚀 deployed

Uh oh!

danny-avila commented May 23, 2026

Uh oh!

chatgpt-codex-connector Bot commented May 23, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

danny-avila commented May 22, 2026 •

edited

Loading