MCP OAuth sometimes fails on first attempt - concurrent reinitializations overwrite PKCE flow state

[m-rucinski]

What happened?

Symptom: First 1–2 OAuth attempts sometimes fail with invalid code verifier from the token endpoint; subsequent retries succeed.

Root cause: GET /:serverName/oauth/initiate calls MCPOAuthHandler.initiateOAuthFlow() which
generates a brand-new PKCE code_verifier + code_challenge on every invocation. However,
MCPConnectionFactory.handleOAuthEvents() already called initiateOAuthFlow() and stored a
different code_verifier in the flow state (via initFlow, packages/api/src/mcp/MCPConnectionFactory.ts ~line 462).
The browser is then redirected to Salesforce with the /initiate route's new code_challenge,
but the OAuth callback retrieves the flow state's original code_verifier for the token exchange —
causing a permanent PKCE mismatch on every first attempt.

Expected behavior: OAuth completes on the first attempt. The stored code_verifier should
match the code_challenge sent to Salesforce, since they are derived from the same PKCE pair

The fix: the /initiate route should redirect to the authorizationUrl already stored in the flow
metadata (metadataWithUrl includes authorizationUrl at initFlow time) rather than generating a
new one. No new code_verifier would be produced and the mismatch would not occur.

Affected file: api/server/routes/mcp.js, GET /:serverName/oauth/initiate handler
Also relevant: packages/api/src/mcp/MCPConnectionFactory.ts handleOAuthEvents(), ~line 435–479
Related merged PR (partial fix — scope on refresh, not PKCE): #13412

Version Information

Version: v0.8.6 (https://github.com/danny-avila/LibreChat/releases/tag/v0.8.6)
Deployment: source install, single instance
Note: PR #13412 (fix/mcp-salesforce-oauth — scope retry on refresh) is not included in this build.

Steps to Reproduce

1. Configure a Salesforce Hosted MCP server in librechat.yaml with an 'oauth' block
   (authorization_url, token_url, client_id, client_secret, redirect_uri, skip_code_challenge_check: true)

mcpServers:
  Salesforce:
    type: streamable-http
    url: https://api.salesforce.com/platform/mcp/v1/custom/<path>
    requiresOAuth: true
    startup: false
    oauth:
      client_id: <redacted>
      client_secret: <redacted>
      authorization_url: https://login.salesforce.com/services/oauth2/authorize
      token_url: https://login.salesforce.com/services/oauth2/token
      redirect_uri: https://<host>/api/mcp/Salesforce/oauth/callback
      scope: mcp_api refresh_token
      skip_code_challenge_check: true

2. Ensure requiresOAuth: true is set so the auth button appears
3. Click "Continue with OAuth" in the MCP server panel
4. Complete the Salesforce login flow
5. Observe: callback returns InvalidGrantError: invalid code verifier and authentication fails
6. Repeat steps 3–4 — on the second or third attempt, authentication succeeds

What browsers are you seeing the problem on?

Chrome, Safari, Firefox, Microsoft Edge
Note: not browser-specific — this is a server-side OAuth flow bug.

Relevant log output

# =============================================================
# CONTEXT: Pre-existing failure from a prior session
# =============================================================
{"error":"invalid code verifier","flowAge":5037,"flowId":"<USER_ID>:Salesforce","flowTTL":180000,"level":"debug","message":"[MCP Connection Status] Found failed OAuth flow for Salesforce","status":"FAILE
D","timedOut":false,"timestamp":"2026-06-05T09:47:06.195Z"}
{"level":"debug","message":"[mcp_oauth:<USER_ID>:Salesforce] Flow completed","timestamp":"2026-06-05T09:47:07.165Z"}
{"level":"debug","message":"[MCP][Salesforce][<USER_ID>] OAuth flow monitor ended invalid code verifier","timestamp":"2026-06-05T09:47:07.166Z"}

# =============================================================
# ATTEMPT 1 — 09:47:33 — FAILS with "invalid code verifier"
# =============================================================
{"level":"info","message":"[MCP Reinitialize] Reinitializing server: Salesforce","timestamp":"2026-06-05T09:47:33.484Z"}
{"level":"info","message":"[MCP][User: <USER_ID>][Salesforce] Establishing new connection","timestamp":"2026-06-05T09:47:33.487Z"}
{"level":"debug","message":"[mcp_get_tokens:<USER_ID>:Salesforce] Flow already exists with valid token","timestamp":"2026-06-05T09:47:33.487Z"}
{"level":"debug","message":"[mcp_get_tokens:<USER_ID>:Salesforce] Flow completed","timestamp":"2026-06-05T09:47:35.488Z"}
{"level":"info","message":"[MCP][Salesforce][<USER_ID>] Loaded OAuth tokens","timestamp":"2026-06-05T09:47:35.488Z"}
{"level":"info","message":"[MCP][User: <USER_ID>][Salesforce] Creating streamable-http transport: https://api.salesforce.com/platform/mcp/v1/custom/<ORG_PATH>","timestamp":"2026-06-05T09:47:35.491Z"}
{"level":"warn","message":"[MCP][User: <USER_ID>][Salesforce] OAuth authentication error detected","timestamp":"2026-06-05T09:47:35.597Z"}
{"code":401,"level":"error","message":"[MCP][User: <USER_ID>][Salesforce] Transport error: Streamable HTTP error: {\"errors\":[{\"message\":\"Invalid token\"}]}","timestamp":"2026-06-05T09:47:35.597Z"}
{"level":"warn","message":"[MCP][User: <USER_ID>][Salesforce] OAuth authentication required","timestamp":"2026-06-05T09:47:35.597Z"}
{"level":"info","message":"[MCP][Salesforce][<USER_ID>] oauthRequired event received","timestamp":"2026-06-05T09:47:35.597Z"}

# MCPConnectionFactory calls initiateOAuthFlow — generates code_verifier_A + state_A
{"level":"debug","message":"[MCPOAuth] initiateOAuthFlow called for Salesforce with URL: https://api.salesforce.com/platform/mcp/v1/custom/<ORG_PATH>","timestamp":"2026-06-05T09:47:35.598Z"}
{"level":"debug","message":"[MCPOAuth] Generated flowId: <USER_ID>:Salesforce, state: 8RBvw7Bc8uzve8dX-HzCgRRJ7HqXmRNETD2tahARCGU","timestamp":"2026-06-05T09:47:35.598Z"}
{"level":"debug","message":"[MCPOAuth] Using pre-configured OAuth settings for Salesforce","timestamp":"2026-06-05T09:47:35.598Z"}
{"level":"debug","message":"[MCPOAuth] Code challenge check skip enabled, forcing S256 support for Salesforce","timestamp":"2026-06-05T09:47:35.598Z"}
{"level":"debug","message":"[MCPOAuth] metadata for \"Salesforce\": {\"authorization_endpoint\":\"https://login.salesforce.com/services/oauth2/authorize\",\"token_endpoint\":\"https://login.salesforce.com/services/oauth2/token\",\"scopes_supported\":[\"mcp_api\",\"refresh_token\"],\"grant_types_supported\":[\"authorization_code\",\"refresh_token\"],\"token_endpoint_auth_methods_supported\":[\"client_secret_post\"],\"response_types_supported\":[\"code\"],\"code_challenge_methods_supported\":[\"S256\",\"plain\"]}","timestamp":"2026-06-05T09:47:35.598Z"}                                                             
{"level":"debug","message":"[MCPOAuth] Authorization URL generated: https://login.salesforce.com/services/oauth2/authorize","timestamp":"2026-06-05T09:47:35.598Z"}

# Flow state stored: code_verifier_A keyed under state_A
{"level":"debug","message":"[mcp_oauth:<USER_ID>:Salesforce] Storing initial flow state","timestamp":"2026-06-05T09:47:35.598Z"}
{"level":"debug","message":"[mcp_oauth_state:8RBvw7Bc8uzve8dX-HzCgRRJ7HqXmRNETD2tahARCGU] Storing initial flow state","timestamp":"2026-06-05T09:47:35.598Z"}
{"level":"info","message":"[MCP][Salesforce][<USER_ID>] OAuth flow started, issuing authorization URL","timestamp":"2026-06-05T09:47:35.598Z"}
{"level":"info","message":"[MCP Reinitialize] OAuth URL received for Salesforce","timestamp":"2026-06-05T09:47:35.598Z"}
{"level":"debug","message":"[mcp_oauth:<USER_ID>:Salesforce] Flow already exists","timestamp":"2026-06-05T09:47:35.598Z"}

# User clicks authenticate → completes Salesforce login → callback arrives
{"level":"debug","message":"[MCP OAuth] Callback received","serverName":"Salesforce","state":"8RBvw7Bc8uzve8dX-HzCgRRJ7HqXmRNETD2tahARCGU","timestamp":"2026-06-05T09:47:38.696Z"}
{"level":"debug","message":"[MCP OAuth] Resolved flow ID from state","flowId":"<USER_ID>:Salesforce","timestamp":"2026-06-05T09:47:38.696Z"}
{"level":"debug","message":"[MCP OAuth] Getting flow state for flowId: <USER_ID>:Salesforce","timestamp":"2026-06-05T09:47:38.696Z"}
{"hasClientInfo":true,"hasCodeVerifier":true,"hasMetadata":true,"level":"debug","message":"[MCP OAuth] Flow state details","serverName":"Salesforce","timestamp":"2026-06-05T09:47:38.697Z"}
{"level":"debug","message":"[MCP OAuth] Completing OAuth flow","timestamp":"2026-06-05T09:47:38.697Z"}
{"level":"warn","message":"[MCP OAuth] oauthHeaders absent from flow state — config-source server oauth_headers will be empty","serverName":"Salesforce","timestamp":"2026-06-05T09:47:38.697Z"}

# ❌ Token exchange fails — code_verifier in flow state does not match code_challenge sent to Salesforce
{"error":{"name":"InvalidGrantError"},"flowId":"<USER_ID>:Salesforce","level":"error","message":"[MCPOAuth] Failed to complete OAuth flow","timestamp":"2026-06-05T09:47:38.870Z"}
{"level":"error","message":"[MCP OAuth] OAuth callback error invalid code verifier","name":"InvalidGrantError","timestamp":"2026-06-05T09:47:38.870Z"}
{"level":"error","message":"Unknown OAuth error","timestamp":"2026-06-05T09:47:38.878Z"}

{"error":"invalid code verifier","flowAge":3572,"flowId":"<USER_ID>:Salesforce","flowTTL":180000,"level":"debug","message":"[MCP Connection Status] Found failed OAuth flow for Salesforce","status":"FAILE
D","timedOut":false,"timestamp":"2026-06-05T09:47:39.171Z"}
{"level":"debug","message":"[mcp_oauth:<USER_ID>:Salesforce] Flow completed","timestamp":"2026-06-05T09:47:39.599Z"}
{"level":"debug","message":"[MCP][Salesforce][<USER_ID>] OAuth flow monitor ended invalid code verifier","timestamp":"2026-06-05T09:47:39.599Z"}

# =============================================================
# ATTEMPT 2 — 09:47:45 — SUCCEEDS
# =============================================================
{"level":"info","message":"[MCP Reinitialize] Reinitializing server: Salesforce","timestamp":"2026-06-05T09:47:45.470Z"}
{"level":"info","message":"[MCP][User: <USER_ID>][Salesforce] Establishing new connection","timestamp":"2026-06-05T09:47:45.473Z"}
{"level":"debug","message":"[mcp_get_tokens:<USER_ID>:Salesforce] Flow already exists with valid token","timestamp":"2026-06-05T09:47:45.473Z"}
{"level":"debug","message":"[mcp_get_tokens:<USER_ID>:Salesforce] Flow completed","timestamp":"2026-06-05T09:47:47.473Z"}
{"level":"info","message":"[MCP][Salesforce][<USER_ID>] Loaded OAuth tokens","timestamp":"2026-06-05T09:47:47.474Z"}
{"level":"info","message":"[MCP][User: <USER_ID>][Salesforce] Creating streamable-http transport: https://api.salesforce.com/platform/mcp/v1/custom/<ORG_PATH>","timestamp":"2026-06-05T09:47:47.474Z"}
{"level":"warn","message":"[MCP][User: <USER_ID>][Salesforce] OAuth authentication error detected","timestamp":"2026-06-05T09:47:47.567Z"}
{"code":401,"level":"error","message":"[MCP][User: <USER_ID>][Salesforce] Transport error: Streamable HTTP error: {\"errors\":[{\"message\":\"Invalid token\"}]}","timestamp":"2026-06-05T09:47:47.567Z"}
{"level":"warn","message":"[MCP][User: <USER_ID>][Salesforce] OAuth authentication required","timestamp":"2026-06-05T09:47:47.567Z"}
{"level":"info","message":"[MCP][Salesforce][<USER_ID>] oauthRequired event received","timestamp":"2026-06-05T09:47:47.567Z"}

# MCPConnectionFactory calls initiateOAuthFlow again — generates DIFFERENT code_verifier_B + state_B
{"level":"debug","message":"[MCPOAuth] initiateOAuthFlow called for Salesforce with URL: https://api.salesforce.com/platform/mcp/v1/custom/<ORG_PATH>","timestamp":"2026-06-05T09:47:47.567Z"}
{"level":"debug","message":"[MCPOAuth] Generated flowId: <USER_ID>:Salesforce, state: i-AEWgzqYuhQVEgaJN2Ts1QeHt3Kuarr82p7jzx5aeA","timestamp":"2026-06-05T09:47:47.567Z"}
{"level":"debug","message":"[MCPOAuth] Using pre-configured OAuth settings for Salesforce","timestamp":"2026-06-05T09:47:47.567Z"}
{"level":"debug","message":"[MCPOAuth] Code challenge check skip enabled, forcing S256 support for Salesforce","timestamp":"2026-06-05T09:47:47.568Z"}
{"level":"debug","message":"[MCPOAuth] Authorization URL generated: https://login.salesforce.com/services/oauth2/authorize","timestamp":"2026-06-05T09:47:47.568Z"}

# Flow state stored: code_verifier_B keyed under state_B (overwrites attempt 1's state)
{"level":"debug","message":"[mcp_oauth:<USER_ID>:Salesforce] Storing initial flow state","timestamp":"2026-06-05T09:47:47.568Z"}
{"level":"debug","message":"[mcp_oauth_state:i-AEWgzqYuhQVEgaJN2Ts1QeHt3Kuarr82p7jzx5aeA] Storing initial flow state","timestamp":"2026-06-05T09:47:47.568Z"}
{"level":"info","message":"[MCP][Salesforce][<USER_ID>] OAuth flow started, issuing authorization URL","timestamp":"2026-06-05T09:47:47.568Z"}
{"level":"info","message":"[MCP Reinitialize] OAuth URL received for Salesforce","timestamp":"2026-06-05T09:47:47.568Z"}
{"level":"debug","message":"[mcp_oauth:<USER_ID>:Salesforce] Flow already exists","timestamp":"2026-06-05T09:47:47.569Z"}

# User clicks authenticate → completes Salesforce login → callback arrives
{"level":"debug","message":"[MCP OAuth] Callback received","serverName":"Salesforce","state":"i-AEWgzqYuhQVEgaJN2Ts1QeHt3Kuarr82p7jzx5aeA","timestamp":"2026-06-05T09:47:50.638Z"}
{"level":"debug","message":"[MCP OAuth] Resolved flow ID from state","flowId":"<USER_ID>:Salesforce","timestamp":"2026-06-05T09:47:50.639Z"}
{"level":"debug","message":"[MCP OAuth] Getting flow state for flowId: <USER_ID>:Salesforce","timestamp":"2026-06-05T09:47:50.639Z"}
{"hasClientInfo":true,"hasCodeVerifier":true,"hasMetadata":true,"level":"debug","message":"[MCP OAuth] Flow state details","serverName":"Salesforce","timestamp":"2026-06-05T09:47:50.639Z"}
{"level":"debug","message":"[MCP OAuth] Completing OAuth flow","timestamp":"2026-06-05T09:47:50.639Z"}
{"level":"warn","message":"[MCP OAuth] oauthHeaders absent from flow state — config-source server oauth_headers will be empty","serverName":"Salesforce","timestamp":"2026-06-05T09:47:50.639Z"}

# ✅ Token exchange succeeds
{"flowId":"<USER_ID>:Salesforce","has_access_token":true,"has_refresh_token":true,"level":"debug","message":"[MCPOAuth] Token exchange successful","scope":"refresh_token mcp_api","timestamp":"2026-06-05T09:47:50.927Z","token_type":"Bearer"}                                                                                                                                                                            
{"level":"info","message":"[MCP OAuth] OAuth flow completed, tokens received in callback route","timestamp":"2026-06-05T09:47:50.928Z"}
{"level":"debug","message":"[MCP][User: <USER_ID>][Salesforce] Using JWT exp claim: 2026-06-05T17:47:50.000Z","timestamp":"2026-06-05T09:47:50.929Z"}
{"level":"debug","message":"[MCP OAuth] Stored OAuth tokens prior to reconnection","serverName":"Salesforce","timestamp":"2026-06-05T09:47:50.946Z"}
{"level":"info","message":"[MCP][User: <USER_ID>][Salesforce] Connection successfully established","timestamp":"2026-06-05T09:47:54.868Z"}
{"level":"info","message":"[MCP OAuth] Successfully reconnected Salesforce for user <USER_ID>","timestamp":"2026-06-05T09:47:54.868Z"}
{"level":"debug","message":"[MCP Cache] Updated 16 tools for server Salesforce","timestamp":"2026-06-05T09:47:54.909Z"}

Screenshots

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[danny-avila]

Note: PR #13412 (fix/mcp-salesforce-oauth — scope retry on refresh) is not included in this build.

I will look into your suggested change but is it a partial fix if you can’t reproduce it without this?

[m-rucinski]

Hi!

Yeah, I can cherry-pick PR #13412 and test to confirm the PKCE mismatch still occurs on fresh OAuth
attempts, but PR #13412 addresses Salesforce rejecting the scope parameter on token refresh (HTTP 400 "scope
parameter not supported").
This reduces forced re-authentications, which would reduce how often the PKCE bug is triggered.
But it does not fix the PKCE mismatch itself imo.

[danny-avila]

Ok I understand, thank you for the detailed report

[jayblast-spec]

The diagnosis in the report is right, and the proposed fix is the correct direction, but I'd push it one step further before calling it done.

The core issue is that "start OAuth for this server" has two independent call sites (MCPConnectionFactory.handleOAuthEvents and the GET /:serverName/oauth/initiate route) that each assume they're the one initiating the flow, so each generates its own PKCE pair and writes it to the flow store under the same flowId. Whichever call writes last wins, and the browser was already sent the earlier one's code_challenge. That's a double-write race, not really an OAuth-specific bug, it's the same shape as any two workers racing to claim the same job id.

Redirecting /initiate to the authorizationUrl already stored in flow metadata, instead of calling initiateOAuthFlow again, fixes the specific repro in the logs, because it turns /initiate from a second writer into a reader. But on its own that's not quite sufficient for full correctness, because it assumes the first initiateOAuthFlow call has already written its state by the time /initiate runs. If those two calls can ever land close enough together that neither has written yet when the other checks (a double click on the auth button, a client retry firing while the first request is still in flight, or two initiate requests hitting two app instances if this is ever run behind more than one process), you're back to two writers, just later in the timeline.

What actually closes this is making the write itself a get-or-create keyed by flowId instead of a check in one place and a write in another. If the flow store is in-process (the mcp_oauth_state:* keys in the logs read like a Map), that's cheap to get right: do the "does a live flow already exist" check and the "create it" write inside one synchronous block with nothing awaited in between, since Node's event loop won't interleave two synchronous blocks even when they're triggered from different call sites. If this ever runs multi-instance behind Redis or similar, a plain check-then-set is genuinely racy across processes, and you'd want a real atomic primitive there, SET key value NX or an equivalent conditional write, not two separate round trips.

One thing worth keeping in the design: flowTTL is 180000ms in the logs, so this can't collapse into "always reuse the first authorizationUrl forever." The semantics you want are get-or-create scoped to a live flow: if a non-expired flow already exists for (userId, serverName), hand back its stored authorizationUrl; only generate a fresh PKCE pair when there's no live flow to attach to. That preserves retries after a real timeout while closing the double-initiate race that's causing the first-attempt failures here.