LibreChat/api/server/routes/mcp.js
lia-by-librechat[bot] 2452f499a8
Some checks failed
Backend Unit Tests / Build packages (push) Waiting to run
Backend Unit Tests / Codegraph select (push) Waiting to run
Backend Unit Tests / TypeScript type checks (push) Blocked by required conditions
Backend Unit Tests / Circular dependency checks (push) Waiting to run
Backend Unit Tests / Tests: api (shard 1/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 2/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 3/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: data-provider (push) Blocked by required conditions
Backend Unit Tests / Tests: data-schemas (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 1/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 2/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 3/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 4/4) (push) Blocked by required conditions
Codegraph E2E Votes / vote (full suite) (push) Waiting to run
Docker Dev Branch Images Build / publish (push) Waiting to run
Docker Dev Images Build / publish (push) Waiting to run
Sync Helm Chart Tags / Ignore non-main push (push) Waiting to run
Sync Helm Chart Tags / Sync chart tags (push) Waiting to run
Frontend Unit Tests / Client build recovery regression (push) Has been cancelled
Frontend Unit Tests / Codegraph select (push) Has been cancelled
Frontend Unit Tests / Build packages (push) Has been cancelled
Sync Locize Translations & Create Translation PR / Sync Translation Keys with Locize (push) Has been cancelled
Frontend Unit Tests / TypeScript type checks (client) (push) Has been cancelled
Frontend Unit Tests / Tests: @librechat/client (push) Has been cancelled
Frontend Unit Tests / Tests: Ubuntu (shard 1/2) (push) Has been cancelled
Frontend Unit Tests / Tests: Ubuntu (shard 2/2) (push) Has been cancelled
Frontend Unit Tests / Vite build verification (push) Has been cancelled
Sync Locize Translations & Create Translation PR / Create Translation PR on Version Published (push) Has been cancelled
🗼 fix: Serialize MCP OAuth Token Refresh Across Replicas (#15993)
* fix: Serialize MCP OAuth token refresh across replicas

`MCPTokenStorage.inflightRefreshes` coalesces refresh-token redemptions
inside one Node process. Behind a load balancer without session affinity,
one user's concurrent requests land on different replicas, each reads the
same not-yet-rotated refresh token and redeems it. RFC 9700 servers treat
the second redemption as replay and revoke the whole grant family, so the
user is asked to authorize the MCP server again.

`forceRefreshTokens` now takes a cross-replica refresh flight before
redeeming, using the same `FlowStateManager.acquireLease` primitive the
OAuth teardown fence uses under a distinct key. A replica that waited for
the flight adopts the tokens the holder rotated instead of redeeming
again; when the flight is still held after the wait window it falls back
to the unfenced redemption every earlier release performed.

* fix: Redeem unfenced when the refresh flight lease store fails

* fix: Fence MCP refresh waiters instead of redeeming unfenced

A waiter that could not take the cross-replica refresh flight fell through to
an unfenced redemption after 10s, while the holder's own stale abort does not
fire until 60s. A refresh taking 11 to 60 seconds therefore still let two
replicas redeem one refresh token, the replay this fence exists to prevent.

The waiter now polls until it either adopts the tokens the holder rotated or
acquires the flight, and fails as MCPTokenRefreshUnavailableError rather than
redeeming beside a live holder. `getTokens` callers defer connection recovery
on that error, and the stored credential is left intact for a later attempt.

The flight is keyed by the stored credential (tenant, user, server name)
rather than the caller's OAuth binding digest, so a rolling config change
cannot hand two replicas different locks over one stored token. The wait is
an operator lever, `oauthRefreshWaitTimeout`, clamped to half the stale
window. An adoption read that fails no longer gives up the held flight.

* fix: Annotate derived refresh-flight constants for isolatedDeclarations

* fix: Recapture the credential generation a peer published on adoption

* fix: Hold the MCP refresh flight until redemption settles

Four corrections to the cross-replica refresh flight.

The flight lease equalled the window that aborts a stalled redemption, on
the claim that an expired flight could never belong to a redemption still
able to reach the token endpoint. Aborting proves no such thing: the
request may have been processed with its response lost, and a stalled
event loop can delay the abort past its own deadline. The lease now
outlives the abort, so a peer cannot redeem a credential the provider has
already rotated. A live replica still releases on settle, so the margin is
paid only by one that died holding the flight.

The credential snapshot was taken after the first failed acquisition, so a
holder that stored and released in that gap was snapshotted post-rotation:
the next attempt saw an unchanged record and redeemed the credential it
should have adopted. It is taken before the first attempt now.

`oauthRefreshWaitTimeout` accepted zero while the runtime mapped every
non-positive value to the default, so the config validated and then
behaved contrary to its value. Zero is rejected at load.

Adoption announced a second credential change through
`handleOAuthRefreshSuccess`, whose `onOAuthCredentialsChanged` advances
authorization state after persistence this replica did not perform. That
retired the generation recaptured beside it and fenced the build against
its own tool publication. Adoption now updates the local token-flow cache
and recaptures, without announcing.

* fix: Check every held MCP refresh flight for a peer's rotation

Four corrections, two of them consequences of moving the credential
observation ahead of the first lease attempt.

That move created a storage read inside `beginRefreshFlight`, and its
failure reached a handler written for a lease-store outage, so a transient
read error became an unfenced redemption beside a live peer. The flight
now handles its own reads: losing the observation costs adoption and
nothing else, and only the lease store failing may redeem unfenced.

The observation was also never compared when the first acquisition
succeeded. A peer that rotated and released before this replica contended
left an acquisition that looked uncontended, and its fresh credential was
redeemed a second time. Every acquisition now runs one rotation check,
which also collapses two code paths into one.

`getTokens` already loads the refresh record to decide a refresh is
needed, so it is passed on as the observation baseline instead of read
again, and the read taken under the flight is reused as the credential
redeemed. Two reads on a latency-counted path where there were three.

`runSilentRefresh` collapsed contention into null, sending the 401 path to
interactive OAuth, so a slow peer prompted the user to authorize a server
whose credential was about to be valid. The retryable outcome now travels
through the silent-refresh layers and the connection defers, matched by
name as well as identity because these errors cross the package boundary.

* chore: Regenerate the Agents OpenAPI spec for repositoryInstructions

The drift check added by #15928 fails on dev: #16008 added
`repositoryInstructions` to the agent schema without regenerating the
committed spec, so every branch merging dev inherits the failure. This is
the remedy the check itself prescribes and carries no hand-written change.
Drop this commit if dev regenerates first.

* fix: preserve MCP refresh outcomes across replica boundaries

* fix: keep MCP adoption fenced through publication

* fix: anchor MCP refresh adoption to rejected credentials

* fix: Complete OAuth Adoption Adapters and Isolate Legacy Flow Readers

* fix: Preserve OAuth Request Identity Through Recovery and Discovery

* fix: Fence OAuth Adoption Against All Credential Writers

* fix: Gate Coordinated OAuth Rollout and Preserve Unauthenticated Identity

* fix: Preserve OAuth Coalescing Across the Staged Rollout

* style: Sort OAuth Timeout Constant Import

* fix: Invalidate Both OAuth Token Flow Protocols on Rotation

* test: Complete the Rollback Token Flow Fixture

---------

Co-authored-by: Lia <lia@librechat.ai>
Co-authored-by: Danny Avila <danny@librechat.ai>
2026-09-16 21:58:23 -04:00

1315 lines
45 KiB
JavaScript

const { Router } = require('express');
const { logger, getTenantId, tenantStorage } = require('@librechat/data-schemas');
const {
CacheKeys,
Constants,
Permissions,
PermissionBits,
PermissionTypes,
} = require('librechat-data-provider');
const {
getBasePath,
createSafeUser,
createAuthIdentityContext,
MCPOAuthHandler,
MCPTokenStorage,
getMCPServerGeneration,
setOAuthSession,
PENDING_STALE_MS,
getUserMCPAuthMap,
validateOAuthCsrf,
OAUTH_CSRF_COOKIE,
setOAuthCsrfCookie,
generateCheckAccess,
validateOAuthSession,
OAUTH_SESSION_COOKIE,
mcpConfig: mcpSettings,
getServerCustomUserVars,
hasCustomUserVars,
requiresEphemeralUserConnection,
MCPAuthenticationRejectedError,
MCPAuthenticationRefreshError,
OpenIDReauthRequiredError,
readMCPRecoveryGenerationAround,
prepareMCPAuthorizationMutation,
persistMCPAuthorizationTransaction,
} = require('@librechat/api');
const {
createMCPServerController,
updateMCPServerController,
deleteMCPServerController,
getMCPServersList,
getMCPServerById,
getMCPTools,
} = require('~/server/controllers/mcp');
const {
getOAuthReconnectionManager,
getMCPServersRegistry,
getFlowStateManager,
getMCPManager,
} = require('~/config');
const {
getServerConnectionStatus,
resolveAllMcpConfigs,
resolveConfigServers,
getMCPSetupData,
} = require('~/server/services/MCP');
const {
requireJwtAuth,
configMiddleware,
canAccessMCPServerResource,
} = require('~/server/middleware');
const { getUserPluginAuthValue } = require('~/server/services/PluginService');
const { maybeUninstallOAuthMCP } = require('~/server/services/MCP/oauthCleanup');
const {
invalidateCachedTools,
getAppConfig,
getMCPToolsCacheGeneration,
} = require('~/server/services/Config');
const { updateMCPServerTools } = require('~/server/services/Config/mcp');
const { reinitMCPServer } = require('~/server/services/Tools/mcp');
const {
clearMCPAuthorizationFenceRetry,
persistMCPAuthorizationFenceRetry,
} = require('~/server/services/MCPAuthorizationFenceRetry');
const { createOpenIDSessionTokenProvider } = require('~/server/services/OpenIDSessionRefresh');
const { getLogStores } = require('~/cache');
const db = require('~/models');
const router = Router();
const OAUTH_CSRF_COOKIE_PATH = '/api/mcp';
const getOAuthFlowId = (userId, serverName) =>
MCPOAuthHandler.generateFlowId(userId, serverName, getTenantId());
const canAccessOAuthFlow = (flowId, userId) => {
const parsed = MCPOAuthHandler.parseFlowId(flowId);
if (!parsed) {
return false;
}
if (parsed.tenantId && parsed.tenantId !== getTenantId()) {
return false;
}
return parsed.userId === userId || parsed.userId === 'system';
};
const checkMCPUsePermissions = generateCheckAccess({
permissionType: PermissionTypes.MCP_SERVERS,
permissions: [Permissions.USE],
getRoleByName: db.getRoleByName,
});
const checkMCPCreate = generateCheckAccess({
permissionType: PermissionTypes.MCP_SERVERS,
permissions: [Permissions.USE, Permissions.CREATE],
getRoleByName: db.getRoleByName,
});
/**
* Get all MCP tools available to the user
* Returns only MCP tools, completely decoupled from regular LibreChat tools
*/
router.get('/tools', requireJwtAuth, configMiddleware, checkMCPUsePermissions, async (req, res) => {
return getMCPTools(req, res);
});
/**
* Initiate OAuth flow
* This endpoint is called when the user clicks the auth link in the UI
*/
router.get('/:serverName/oauth/initiate', requireJwtAuth, setOAuthSession, async (req, res) => {
try {
const { serverName } = req.params;
const { userId, flowId } = req.query;
const user = req.user;
// Verify the userId matches the authenticated user
if (typeof userId !== 'string' || userId !== user.id) {
return res.status(403).json({ error: 'User mismatch' });
}
const expectedFlowId = getOAuthFlowId(user.id, serverName);
if (typeof flowId !== 'string' || flowId !== expectedFlowId) {
logger.error('[MCP OAuth] Invalid flow ID for initiate request', {
serverName,
userId,
flowId,
expectedFlowId,
});
return res.status(403).json({ error: 'Flow mismatch' });
}
logger.debug('[MCP OAuth] Initiate request', { serverName, userId, flowId });
const flowsCache = getLogStores(CacheKeys.FLOWS);
const flowManager = getFlowStateManager(flowsCache);
/** Flow state to retrieve OAuth config */
const flowState = await flowManager.getFlowState(flowId, 'mcp_oauth');
if (!flowState) {
logger.error('[MCP OAuth] Flow state not found', { flowId });
return res.status(404).json({ error: 'Flow not found' });
}
const {
authorizationUrl: storedAuthorizationUrl,
serverName: flowServerName,
userId: flowUserId,
serverUrl,
oauth: oauthConfig,
} = flowState.metadata || {};
if (flowUserId && flowUserId !== user.id) {
logger.error('[MCP OAuth] Flow user mismatch', { flowId, userId, flowUserId });
return res.status(403).json({ error: 'User mismatch' });
}
if (flowServerName && flowServerName !== serverName) {
logger.error('[MCP OAuth] Flow server mismatch', { flowId, serverName, flowServerName });
return res.status(400).json({ error: 'Invalid flow state' });
}
const pendingAge = flowState.createdAt ? Date.now() - flowState.createdAt : Infinity;
const isFreshPendingFlow = flowState.status === 'PENDING' && pendingAge < PENDING_STALE_MS;
if (!isFreshPendingFlow) {
logger.error('[MCP OAuth] Flow is not active for initiation', {
flowId,
status: flowState.status,
pendingAge,
});
return res.status(400).json({ error: 'Invalid flow state' });
}
if (typeof storedAuthorizationUrl === 'string' && storedAuthorizationUrl.length > 0) {
logger.debug('[MCP OAuth] Reusing stored authorization URL', {
serverName,
userId,
flowId,
});
setOAuthCsrfCookie(res, flowId, OAUTH_CSRF_COOKIE_PATH);
return res.redirect(storedAuthorizationUrl);
}
if (!serverUrl || !oauthConfig) {
logger.error('[MCP OAuth] Missing server URL or OAuth config in flow state');
return res.status(400).json({ error: 'Invalid flow state' });
}
const configServers = await resolveConfigServers(req);
const oauthHeaders = await getOAuthHeaders(serverName, userId, configServers);
const registry = getMCPServersRegistry();
const { allowedDomains, allowedAddresses } = await registry.resolveAllowlists({
userId,
role: req.user?.role,
});
const {
authorizationUrl,
flowId: oauthFlowId,
flowMetadata,
} = await MCPOAuthHandler.initiateOAuthFlow(
serverName,
serverUrl,
userId,
oauthHeaders,
oauthConfig,
allowedDomains,
undefined,
allowedAddresses,
getTenantId(),
);
logger.debug('[MCP OAuth] OAuth flow initiated', { oauthFlowId, authorizationUrl });
const oldState = flowState.metadata?.state;
if (typeof oldState === 'string') {
await MCPOAuthHandler.deleteStateMapping(oldState, flowManager);
}
const effectiveConfig = (await resolveAllMcpConfigs(userId))?.[serverName];
const metadataWithUrl = {
...flowMetadata,
authorizationUrl,
tenantId: getTenantId(),
...(effectiveConfig && { serverGeneration: getMCPServerGeneration(effectiveConfig) }),
};
await flowManager.initFlow(oauthFlowId, 'mcp_oauth', metadataWithUrl);
await MCPOAuthHandler.storeStateMapping(flowMetadata.state, oauthFlowId, flowManager);
setOAuthCsrfCookie(res, oauthFlowId, OAUTH_CSRF_COOKIE_PATH);
res.redirect(authorizationUrl);
} catch (error) {
logger.error('[MCP OAuth] Failed to initiate OAuth', error);
res.status(500).json({ error: 'Failed to initiate OAuth' });
}
});
/**
* OAuth callback handler
* This handles the OAuth callback after the user has authorized the application
*/
router.get('/:serverName/oauth/callback', async (req, res) => {
const basePath = getBasePath();
try {
const { serverName } = req.params;
const { code, state, error: oauthError } = req.query;
logger.debug('[MCP OAuth] Callback received', {
serverName,
code: code ? 'present' : 'missing',
state,
error: oauthError,
});
if (oauthError) {
logger.error('[MCP OAuth] OAuth error received', { error: oauthError });
// Gate failFlow behind callback validation to prevent DoS via leaked state
if (state && typeof state === 'string') {
try {
const flowsCache = getLogStores(CacheKeys.FLOWS);
const flowManager = getFlowStateManager(flowsCache);
const flowId = await MCPOAuthHandler.resolveStateToFlowId(state, flowManager);
if (flowId) {
const parsed = MCPOAuthHandler.parseFlowId(flowId);
if (!parsed) {
logger.warn('[MCP OAuth] Invalid flow ID format for OAuth error callback', {
flowId,
});
} else {
const hasCsrf = validateOAuthCsrf(req, res, flowId, OAUTH_CSRF_COOKIE_PATH);
const hasSession = !hasCsrf && validateOAuthSession(req, parsed.userId);
if (hasCsrf || hasSession) {
/** A stale mapping can resolve a superseded attempt's state to the
* current flow (deterministic flow ids); only fail the flow this
* error callback actually belongs to */
const currentFlow = await flowManager.getFlowState(flowId, 'mcp_oauth');
const flowMeta = currentFlow?.metadata;
if (currentFlow && flowMeta?.state === state) {
await flowManager.failFlowIfCurrent(
flowId,
'mcp_oauth',
currentFlow.createdAt,
state,
String(oauthError),
);
logger.debug('[MCP OAuth] Marked flow as FAILED with OAuth error', {
flowId,
error: oauthError,
});
} else {
logger.warn('[MCP OAuth] Skipping failFlow for superseded OAuth error callback', {
flowId,
});
}
}
}
}
} catch (err) {
logger.debug('[MCP OAuth] Could not mark flow as failed', err);
}
}
return res.redirect(
`${basePath}/oauth/error?error=${encodeURIComponent(String(oauthError))}`,
);
}
if (!code || typeof code !== 'string') {
logger.error('[MCP OAuth] Missing or invalid code');
return res.redirect(`${basePath}/oauth/error?error=missing_code`);
}
if (!state || typeof state !== 'string') {
logger.error('[MCP OAuth] Missing or invalid state');
return res.redirect(`${basePath}/oauth/error?error=missing_state`);
}
const flowsCache = getLogStores(CacheKeys.FLOWS);
const flowManager = getFlowStateManager(flowsCache);
const flowId = await MCPOAuthHandler.resolveStateToFlowId(state, flowManager);
if (!flowId) {
logger.error('[MCP OAuth] Could not resolve state to flow ID', { state });
return res.redirect(`${basePath}/oauth/error?error=invalid_state`);
}
logger.debug('[MCP OAuth] Resolved flow ID from state', { flowId });
const parsedFlowId = MCPOAuthHandler.parseFlowId(flowId);
if (!parsedFlowId) {
logger.error('[MCP OAuth] Invalid flow ID format', { flowId });
return res.redirect(`${basePath}/oauth/error?error=invalid_state`);
}
const hasCsrf = validateOAuthCsrf(req, res, flowId, OAUTH_CSRF_COOKIE_PATH);
const hasSession = !hasCsrf && validateOAuthSession(req, parsedFlowId.userId);
let hasActiveFlow = false;
if (!hasCsrf && !hasSession) {
const pendingFlow = await flowManager.getFlowState(flowId, 'mcp_oauth');
const pendingAge = pendingFlow?.createdAt ? Date.now() - pendingFlow.createdAt : Infinity;
hasActiveFlow = pendingFlow?.status === 'PENDING' && pendingAge < PENDING_STALE_MS;
if (hasActiveFlow) {
logger.debug(
'[MCP OAuth] CSRF/session cookies absent, validating via active PENDING flow',
{
flowId,
},
);
}
}
if (!hasCsrf && !hasSession && !hasActiveFlow) {
logger.error(
'[MCP OAuth] CSRF validation failed: no valid CSRF cookie, session cookie, or active flow',
{
flowId,
hasCsrfCookie: !!req.cookies?.[OAUTH_CSRF_COOKIE],
hasSessionCookie: !!req.cookies?.[OAUTH_SESSION_COOKIE],
},
);
return res.redirect(`${basePath}/oauth/error?error=csrf_validation_failed`);
}
logger.debug('[MCP OAuth] Getting flow state for flowId: ' + flowId);
const flowState = await MCPOAuthHandler.getFlowState(flowId, flowManager);
if (!flowState) {
logger.error('[MCP OAuth] Flow state not found for flowId:', flowId);
return res.redirect(`${basePath}/oauth/error?error=invalid_state`);
}
/**
* Flow ids are deterministic (userId:serverName), so a stale state mapping
* can resolve to a newer flow for the same server. The stored state is the
* only per-attempt nonce; a mismatch means this callback belongs to a
* superseded authorization attempt and must not consume the current flow.
*/
if (flowState.state !== state) {
logger.error('[MCP OAuth] State mismatch for flow', { flowId, serverName });
return res.redirect(`${basePath}/oauth/error?error=invalid_state`);
}
logger.debug('[MCP OAuth] Flow state details', {
serverName: flowState.serverName,
userId: flowState.userId,
hasMetadata: !!flowState.metadata,
hasClientInfo: !!flowState.clientInfo,
hasCodeVerifier: !!flowState.codeVerifier,
});
/** Check if this flow has already been completed (idempotency protection) */
const currentFlowState = await flowManager.getFlowState(flowId, 'mcp_oauth');
if (!currentFlowState) {
logger.warn('[MCP OAuth] Flow disappeared before token exchange', { flowId, serverName });
return res.redirect(`${basePath}/oauth/error?error=invalid_state`);
}
if (currentFlowState.status === 'COMPLETED') {
logger.warn('[MCP OAuth] Flow already completed, preventing duplicate token exchange', {
flowId,
serverName,
});
return res.redirect(`${basePath}/oauth/success?serverName=${encodeURIComponent(serverName)}`);
}
const isStalePendingFlow =
currentFlowState?.status === 'PENDING' &&
(!currentFlowState.createdAt || Date.now() - currentFlowState.createdAt >= PENDING_STALE_MS);
if (currentFlowState?.status === 'FAILED' || isStalePendingFlow) {
logger.warn('[MCP OAuth] Refusing token exchange for terminal flow', {
flowId,
serverName,
status: currentFlowState.status,
});
return res.redirect(`${basePath}/oauth/error?error=invalid_state`);
}
logger.debug('[MCP OAuth] Completing OAuth flow');
/**
* Restore tenant context for the callback body. The callback is a cross-origin
* redirect from the OAuth provider, so SameSite=Strict cookies (including the
* JWT) are not sent. The tenantId was stored in the flow metadata at initiation
* time when the user was authenticated.
*/
const runWithTenant = async (fn) => {
const flowTenantId = flowState.tenantId;
if (flowTenantId && !getTenantId()) {
return tenantStorage.run({ tenantId: flowTenantId }, fn);
}
return fn();
};
await runWithTenant(async () => {
const oauthHeaders =
flowState.oauthHeaders ?? (await getOAuthHeaders(serverName, flowState.userId));
let recoveryPolicy;
const resolveActiveServer = async () => {
const [configs, appConfig] = await Promise.all([
resolveAllMcpConfigs(flowState.userId),
getAppConfig({ userId: flowState.userId, tenantId: getTenantId() }),
]);
recoveryPolicy = appConfig?.mcpSettings?.catalogRecovery;
const activeConfig =
configs?.[serverName] ??
appConfig?.mcpConfig?.[serverName] ??
(await getMCPServersRegistry().getServerConfig(serverName, flowState.userId));
if (!activeConfig) {
return false;
}
if (flowState.serverGeneration) {
return getMCPServerGeneration(activeConfig) === flowState.serverGeneration;
}
return activeConfig.url === flowState.serverUrl;
};
if (!(await resolveActiveServer())) {
throw new Error(`MCP server ${serverName} was deleted during OAuth authorization`);
}
const rollbackStoredTokens = async (storedTokens) => {
const storedMetadata = MCPOAuthHandler.buildStoredClientMetadata(
flowState.metadata,
flowState.resourceMetadata,
flowState.serverUrl,
flowState.clientSource,
);
const revocationMetadata = {
serverUrl: flowState.serverUrl,
clientId: flowState.clientInfo?.client_id ?? '',
clientSecret: flowState.clientInfo?.client_secret ?? '',
revocationEndpoint: storedMetadata?.revocation_endpoint,
revocationEndpointAuthMethodsSupported:
storedMetadata?.revocation_endpoint_auth_methods_supported,
};
for (const [tokenType, token] of [
['access', storedTokens.access_token],
['refresh', storedTokens.refresh_token],
]) {
if (!token) {
continue;
}
try {
await MCPOAuthHandler.revokeOAuthToken(
serverName,
token,
tokenType,
revocationMetadata,
oauthHeaders,
flowState.allowedDomains,
flowState.allowedAddresses,
);
} catch (error) {
logger.warn(
`[MCP OAuth] Failed to revoke ${tokenType} token after callback cancellation:`,
error,
);
}
}
await MCPTokenStorage.deleteUserTokens({
userId: flowState.userId,
serverName,
deleteToken: async (filter) => {
await db.deleteTokens({
...filter,
metadataCredentialSetId: storedTokens.credential_set_id,
});
},
});
};
const tokens = await MCPOAuthHandler.completeOAuthFlow(
flowId,
code,
flowManager,
oauthHeaders,
async (exchangedTokens, completePersistedFlow) => {
if (!flowState?.userId) {
return exchangedTokens;
}
let storedTokens;
try {
const tokenFlowId = MCPOAuthHandler.generateTokenFlowId(
flowState.userId,
serverName,
flowState.tenantId,
);
storedTokens = await persistMCPAuthorizationTransaction(
{
scope: { userId: flowState.userId, serverName },
flowIds: [tokenFlowId, flowId],
tokens: exchangedTokens,
completeAuthorization: completePersistedFlow,
persistTokens: async (candidateTokens, onStoreCommitted) =>
(await MCPTokenStorage.storeTokens({
flowManager,
persistenceWaitTimeoutMs: flowState.oauthPersistenceWaitTimeout,
userId: flowState.userId,
serverName,
tokens: candidateTokens,
createToken: db.createToken,
updateToken: db.updateToken,
deleteTokens: db.deleteTokens,
findToken: db.findToken,
clientInfo: flowState.clientInfo,
metadata: MCPOAuthHandler.buildStoredClientMetadata(
flowState.metadata,
flowState.resourceMetadata,
flowState.serverUrl,
flowState.clientSource,
),
onStoreCommitted,
})) ?? candidateTokens,
},
{
ensureServerActive: resolveActiveServer,
inactiveServerError: () =>
new Error(`MCP server ${serverName} was deleted during OAuth authorization`),
invalidateRecoveryGeneration: invalidateCachedTools,
clearLocalRecovery: (userId, changedServerName) =>
getMCPManager()?.clearCatalogRecoveryState?.(userId, changedServerName),
persistPublicationRetry: persistMCPAuthorizationFenceRetry,
clearPublicationRetry: clearMCPAuthorizationFenceRetry,
retryDelaysMs: recoveryPolicy?.authorizationFenceRetryMs,
attemptTimeoutMs: recoveryPolicy?.authorizationFenceTimeoutMs,
flowManager,
onTokenFlowError: (phase, error) =>
logger.warn(
phase === 'prepare'
? '[MCP OAuth] Failed to clear cached token flow state'
: '[MCP OAuth] Failed to wake a pending token flow',
error,
),
},
);
logger.debug('[MCP OAuth] Stored OAuth tokens before completing callback flow', {
serverName,
userId: flowState.userId,
});
} catch (error) {
logger.error('[MCP OAuth] Failed to store OAuth tokens before flow completion', error);
throw error;
}
return storedTokens;
},
rollbackStoredTokens,
{ createdAt: currentFlowState.createdAt, state },
);
logger.info('[MCP OAuth] OAuth flow completed, tokens received in callback route');
try {
if (flowState.userId !== 'system') {
const user = { id: flowState.userId };
/** Merged config (incl. Config-tier overlays) so the reconnection and
* the cache gate both see request-scoped servers the base registry
* lookup misses */
let serverConfig;
try {
const allConfigs = await resolveAllMcpConfigs(flowState.userId);
serverConfig = allConfigs?.[serverName];
} catch (error) {
logger.warn(
`[MCP OAuth] Could not resolve server config for ${serverName} before reconnecting:`,
error,
);
}
const requestScoped = serverConfig
? requiresEphemeralUserConnection(serverConfig)
: false;
if (requestScoped) {
logger.info(
`[MCP OAuth] Deferring post-OAuth connection for request-scoped server ${serverName} until its first chat use`,
);
getOAuthReconnectionManager().clearReconnection(flowState.userId, serverName);
} else {
const mcpManager = getMCPManager(flowState.userId);
logger.debug(`[MCP OAuth] Attempting to reconnect ${serverName} with new OAuth tokens`);
/**
* Without this, getUserConnection resolves `headers`/`oauth_headers`
* customUserVars templates (e.g. `{{MY_VAR}}`) with no substitution
* data, so the literal placeholder is sent on this first post-callback
* connection attempt even though the user's value is already saved -
* surfaces upstream as a generic auth rejection from the MCP server.
* The other reconnect path (oauth/reinitialize route below) already
* resolves this the same way; this one was missing it.
*/
let userMCPAuthMap;
if (serverConfig?.customUserVars && typeof serverConfig.customUserVars === 'object') {
try {
userMCPAuthMap = await getUserMCPAuthMap({
userId: flowState.userId,
servers: [serverName],
findPluginAuthsByKeys: db.findPluginAuthsByKeys,
});
} catch (error) {
logger.warn(
`[MCP OAuth] Could not resolve customUserVars for ${serverName} before reconnecting:`,
error,
);
}
}
const customUserVars = getServerCustomUserVars(userMCPAuthMap, serverName);
const { snapshot, publicationGeneration } = await mcpManager.withUserConnectionLease(
{
user,
serverName,
flowManager,
serverConfig,
customUserVars,
tokenMethods: {
findToken: db.findToken,
updateToken: db.updateToken,
createToken: db.createToken,
deleteTokens: db.deleteTokens,
},
onOAuthCredentialsChanging: (scope) =>
prepareMCPAuthorizationMutation(scope, {
invalidateRecoveryGeneration: invalidateCachedTools,
persistPublicationRetry: persistMCPAuthorizationFenceRetry,
clearPublicationRetry: clearMCPAuthorizationFenceRetry,
clearLocalRecovery: (userId, changedServerName) =>
getMCPManager()?.clearCatalogRecoveryState?.(userId, changedServerName),
retryDelaysMs: recoveryPolicy?.authorizationFenceRetryMs,
attemptTimeoutMs: recoveryPolicy?.authorizationFenceTimeoutMs,
}),
},
async (userConnection) => {
logger.info(
`[MCP OAuth] Successfully reconnected ${serverName} for user ${flowState.userId}`,
);
const oauthReconnectionManager = getOAuthReconnectionManager();
oauthReconnectionManager.clearReconnection(flowState.userId, serverName);
const snapshot =
typeof userConnection.fetchOrderedToolsSnapshot === 'function'
? await userConnection.fetchOrderedToolsSnapshot()
: await userConnection.fetchToolsSnapshot();
return {
snapshot,
publicationGeneration: mcpManager.getToolPublicationGeneration?.(userConnection),
};
},
);
if (snapshot.complete) {
await updateMCPServerTools({
userId: flowState.userId,
serverName,
tools: snapshot.tools,
serverConfig,
publicationGeneration,
});
} else {
logger.warn(
`[MCP OAuth] Preserving cached tools for ${serverName} because tools/list returned an incomplete snapshot`,
);
}
}
} else {
logger.debug(`[MCP OAuth] System-level OAuth completed for ${serverName}`);
}
} catch (error) {
logger.warn(
`[MCP OAuth] Failed to reconnect ${serverName} after OAuth, but tokens are saved:`,
error,
);
}
/** ID of the flow that the tool/connection is waiting for */
const toolFlowId = flowState.metadata?.toolFlowId;
if (toolFlowId) {
logger.debug('[MCP OAuth] Completing tool flow', { toolFlowId });
const completed = await flowManager.completeFlow(toolFlowId, 'mcp_oauth', tokens);
if (!completed) {
logger.warn(
'[MCP OAuth] Tool flow state not found during completion — waiter will time out',
{ toolFlowId },
);
}
}
}); /* end runWithTenant */
/** Redirect to success page with flowId and serverName */
const redirectUrl = `${basePath}/oauth/success?serverName=${encodeURIComponent(serverName)}`;
res.redirect(redirectUrl);
} catch (error) {
logger.error('[MCP OAuth] OAuth callback error', error);
res.redirect(`${basePath}/oauth/error?error=callback_failed`);
}
});
/**
* Get OAuth tokens for a completed flow
* This is primarily for user-level OAuth flows
*/
router.get('/oauth/tokens/:flowId', requireJwtAuth, async (req, res) => {
try {
const { flowId } = req.params;
const user = req.user;
if (!user?.id) {
return res.status(401).json({ error: 'User not authenticated' });
}
if (!canAccessOAuthFlow(flowId, user.id)) {
return res.status(403).json({ error: 'Access denied' });
}
const flowsCache = getLogStores(CacheKeys.FLOWS);
const flowManager = getFlowStateManager(flowsCache);
const flowState = await flowManager.getFlowState(flowId, 'mcp_oauth');
if (!flowState) {
return res.status(404).json({ error: 'Flow not found' });
}
if (flowState.status !== 'COMPLETED') {
return res.status(400).json({ error: 'Flow not completed' });
}
res.json({ tokens: flowState.result });
} catch (error) {
logger.error('[MCP OAuth] Failed to get tokens', error);
res.status(500).json({ error: 'Failed to get tokens' });
}
});
/**
* Set CSRF binding cookie for OAuth flows initiated outside of HTTP request/response
* (e.g. during chat via SSE). The frontend should call this before opening the OAuth URL
* so the callback can verify the browser matches the flow initiator.
*/
router.post('/:serverName/oauth/bind', requireJwtAuth, setOAuthSession, async (req, res) => {
try {
const { serverName } = req.params;
const user = req.user;
if (!user?.id) {
return res.status(401).json({ error: 'User not authenticated' });
}
const flowId = getOAuthFlowId(user.id, serverName);
setOAuthCsrfCookie(res, flowId, OAUTH_CSRF_COOKIE_PATH);
res.json({ success: true });
} catch (error) {
logger.error('[MCP OAuth] Failed to set CSRF binding cookie', error);
res.status(500).json({ error: 'Failed to bind OAuth flow' });
}
});
/**
* Check OAuth flow status
* This endpoint can be used to poll the status of an OAuth flow
*/
router.get('/oauth/status/:flowId', requireJwtAuth, async (req, res) => {
try {
const { flowId } = req.params;
const user = req.user;
if (!user?.id) {
return res.status(401).json({ error: 'User not authenticated' });
}
if (!canAccessOAuthFlow(flowId, user.id)) {
return res.status(403).json({ error: 'Access denied' });
}
const flowsCache = getLogStores(CacheKeys.FLOWS);
const flowManager = getFlowStateManager(flowsCache);
const flowState = await flowManager.getFlowState(flowId, 'mcp_oauth');
if (!flowState) {
return res.status(404).json({ error: 'Flow not found' });
}
res.json({
status: flowState.status,
completed: flowState.status === 'COMPLETED',
failed: flowState.status === 'FAILED',
error: flowState.error,
});
} catch (error) {
logger.error('[MCP OAuth] Failed to get flow status', error);
res.status(500).json({ error: 'Failed to get flow status' });
}
});
/**
* Cancel OAuth flow
* This endpoint cancels a pending OAuth flow
*/
router.post('/oauth/cancel/:serverName', requireJwtAuth, async (req, res) => {
try {
const { serverName } = req.params;
const user = req.user;
if (!user?.id) {
return res.status(401).json({ error: 'User not authenticated' });
}
logger.info(`[MCP OAuth Cancel] Cancelling OAuth flow for ${serverName} by user ${user.id}`);
const flowsCache = getLogStores(CacheKeys.FLOWS);
const flowManager = getFlowStateManager(flowsCache);
const flowId = getOAuthFlowId(user.id, serverName);
const flowState = await flowManager.getFlowState(flowId, 'mcp_oauth');
if (!flowState) {
logger.debug(`[MCP OAuth Cancel] No active flow found for ${serverName}`);
return res.json({
success: true,
message: 'No active OAuth flow to cancel',
});
}
await MCPOAuthHandler.failFlowAndDeleteStateMapping(
flowId,
flowState,
flowManager,
'User cancelled OAuth flow',
);
logger.info(`[MCP OAuth Cancel] Successfully cancelled OAuth flow for ${serverName}`);
res.json({
success: true,
message: `OAuth flow for ${serverName} cancelled successfully`,
});
} catch (error) {
logger.error('[MCP OAuth Cancel] Failed to cancel OAuth flow', error);
res.status(500).json({ error: 'Failed to cancel OAuth flow' });
}
});
function createMCPStatusRuntimeContext(user, mcpConfig, serverNames) {
const customUserVarServers = serverNames.filter((serverName) => {
const customUserVars = mcpConfig[serverName]?.customUserVars;
return (
customUserVars && typeof customUserVars === 'object' && Object.keys(customUserVars).length > 0
);
});
let userMCPAuthMapPromise;
let mcpAllowlistsPromise;
const loadUserMCPAuthMap = () => {
if (!customUserVarServers.length) {
return Promise.resolve(undefined);
}
userMCPAuthMapPromise ??= getUserMCPAuthMap({
userId: user.id,
servers: customUserVarServers,
findPluginAuthsByKeys: db.findPluginAuthsByKeys,
});
return userMCPAuthMapPromise;
};
const loadMCPAllowlists = () => {
mcpAllowlistsPromise ??= getMCPServersRegistry().resolveAllowlists({
userId: user.id,
role: user.role,
});
return mcpAllowlistsPromise;
};
return { user: createSafeUser(user), loadUserMCPAuthMap, loadMCPAllowlists };
}
function getMCPReinitializeOAuthTimeout(oauthExpiresAt) {
if (typeof oauthExpiresAt !== 'number' || !Number.isFinite(oauthExpiresAt)) {
return mcpSettings.OAUTH_HANDLING_TIMEOUT;
}
return Math.max(0, oauthExpiresAt - Date.now());
}
/**
* Reinitialize MCP server
* This endpoint allows reinitializing a specific MCP server
*/
router.post(
'/:serverName/reinitialize',
requireJwtAuth,
configMiddleware,
checkMCPUsePermissions,
setOAuthSession,
async (req, res, next) => {
try {
const { serverName } = req.params;
const user = createSafeUser(req.user);
if (!user.id) {
return res.status(401).json({ error: 'User not authenticated' });
}
logger.info(`[MCP Reinitialize] Reinitializing server: ${serverName}`);
const mcpManager = getMCPManager();
const configServers = await resolveConfigServers(req);
const serverConfig = await getMCPServersRegistry().getServerConfig(
serverName,
user.id,
configServers,
);
if (!serverConfig) {
return res.status(404).json({
error: `MCP server '${serverName}' not found in configuration`,
});
}
try {
await invalidateCachedTools({ userId: user.id, serverName });
} finally {
await mcpManager.disconnectUserConnection(user.id, serverName);
}
logger.info(
`[MCP Reinitialize] Disconnected existing user connection for server: ${serverName}`,
);
/** @type {Record<string, Record<string, string>> | undefined} */
let userMCPAuthMap;
if (serverConfig.customUserVars && typeof serverConfig.customUserVars === 'object') {
userMCPAuthMap = await getUserMCPAuthMap({
userId: user.id,
servers: [serverName],
findPluginAuthsByKeys: db.findPluginAuthsByKeys,
});
}
const oboIdentityContext = createAuthIdentityContext({
user: req.user,
tenantId: getTenantId(),
});
const result = await reinitMCPServer({
user,
serverName,
serverConfig,
configServers,
userMCPAuthMap,
upstreamTokenProvider: createOpenIDSessionTokenProvider({
req,
res,
user: req.user,
identityContext: oboIdentityContext,
tokenPreference: 'access_token',
}),
oboIdentityContext,
recoveryPolicy: req.config?.mcpSettings?.catalogRecovery,
});
if (!result) {
return res.status(500).json({ error: 'Failed to reinitialize MCP server for user' });
}
const {
success,
message,
oauthRequired,
oauthUrl,
oauthExpiresAt,
failureReason,
missingUserVars,
connectionDeferred,
} = result;
let flowId;
if (oauthRequired) {
flowId = getOAuthFlowId(user.id, serverName);
setOAuthCsrfCookie(res, flowId, OAUTH_CSRF_COOKIE_PATH);
}
res.json({
success,
message,
oauthUrl,
flowId,
oauthTimeout: oauthRequired ? getMCPReinitializeOAuthTimeout(oauthExpiresAt) : undefined,
serverName,
oauthRequired,
failureReason,
missingUserVars,
connectionDeferred,
});
} catch (error) {
if (
error instanceof MCPAuthenticationRejectedError ||
error instanceof MCPAuthenticationRefreshError ||
error instanceof OpenIDReauthRequiredError
) {
return next(error);
}
logger.error('[MCP Reinitialize] Unexpected error', error);
res.status(500).json({ error: 'Internal server error' });
}
},
);
/**
* Get connection status for all MCP servers
* This endpoint returns all app level and user-scoped connection statuses from MCPManager without disconnecting idle connections
*/
router.get('/connection/status', requireJwtAuth, configMiddleware, async (req, res) => {
try {
const user = req.user;
if (!user?.id) {
return res.status(401).json({ error: 'User not authenticated' });
}
const { mcpConfig, appConnections, userConnections, oauthServers } = await getMCPSetupData(
user.id,
{ role: user.role, tenantId: getTenantId(), appConfig: req.config },
);
const runtimeContext = createMCPStatusRuntimeContext(user, mcpConfig, Object.keys(mcpConfig));
const connectionStatus = Object.fromEntries(
await Promise.all(
Object.entries(mcpConfig).map(async ([serverName, config]) => {
try {
const { value: status, generation: authorizationGeneration } =
await readMCPRecoveryGenerationAround(
{ userId: user.id, serverName },
getMCPToolsCacheGeneration,
() =>
getServerConnectionStatus(
user.id,
serverName,
config,
appConnections,
userConnections,
oauthServers,
runtimeContext,
),
{
timeoutMs: req.config?.mcpSettings?.catalogRecovery?.generationReadTimeoutMs,
},
);
return [serverName, { ...status, authorizationGeneration }];
} catch (error) {
const message = `Failed to get status for server "${serverName}"`;
logger.error(`[MCP Connection Status] ${message},`, error);
return [
serverName,
{
connectionState: 'error',
requiresOAuth: oauthServers.has(serverName),
...(requiresEphemeralUserConnection(config) && { requestScoped: true }),
...(requiresEphemeralUserConnection(config) &&
hasCustomUserVars(config) && { configurationState: 'needs_configuration' }),
authorizationState: oauthServers.has(serverName) ? 'error' : 'not_required',
error: message,
},
];
}
}),
),
);
res.json({
success: true,
connectionStatus,
oauthTimeout: mcpSettings.OAUTH_HANDLING_TIMEOUT,
});
} catch (error) {
logger.error('[MCP Connection Status] Failed to get connection status', error);
res.status(500).json({ error: 'Failed to get connection status' });
}
});
/**
* Get connection status for a single MCP server
* This endpoint returns the connection status for a specific server for a given user
*/
router.get('/connection/status/:serverName', requireJwtAuth, configMiddleware, async (req, res) => {
try {
const user = req.user;
const { serverName } = req.params;
if (!user?.id) {
return res.status(401).json({ error: 'User not authenticated' });
}
const { mcpConfig, appConnections, userConnections, oauthServers } = await getMCPSetupData(
user.id,
{ role: user.role, tenantId: getTenantId(), appConfig: req.config },
);
if (!mcpConfig[serverName]) {
return res
.status(404)
.json({ error: `MCP server '${serverName}' not found in configuration` });
}
const runtimeContext = createMCPStatusRuntimeContext(user, mcpConfig, [serverName]);
const { value: serverStatus, generation: authorizationGeneration } =
await readMCPRecoveryGenerationAround(
{ userId: user.id, serverName },
getMCPToolsCacheGeneration,
() =>
getServerConnectionStatus(
user.id,
serverName,
mcpConfig[serverName],
appConnections,
userConnections,
oauthServers,
runtimeContext,
),
{
timeoutMs: req.config?.mcpSettings?.catalogRecovery?.generationReadTimeoutMs,
},
);
res.json({
success: true,
serverName,
connectionStatus: serverStatus.connectionState,
requiresOAuth: serverStatus.requiresOAuth,
requestScoped: serverStatus.requestScoped,
configurationState: serverStatus.configurationState,
authorizationState: serverStatus.authorizationState,
authorizationGeneration,
});
} catch (error) {
logger.error(
`[MCP Per-Server Status] Failed to get connection status for ${req.params.serverName}`,
error,
);
res.status(500).json({ error: 'Failed to get connection status' });
}
});
/**
* Check which authentication values exist for a specific MCP server
* This endpoint returns only boolean flags indicating if values are set, not the actual values
*/
router.get('/:serverName/auth-values', requireJwtAuth, checkMCPUsePermissions, async (req, res) => {
try {
const { serverName } = req.params;
const user = req.user;
if (!user?.id) {
return res.status(401).json({ error: 'User not authenticated' });
}
const configServers = await resolveConfigServers(req);
const serverConfig = await getMCPServersRegistry().getServerConfig(
serverName,
user.id,
configServers,
);
if (!serverConfig) {
return res.status(404).json({
error: `MCP server '${serverName}' not found in configuration`,
});
}
const pluginKey = `${Constants.mcp_prefix}${serverName}`;
const authValueFlags = {};
if (serverConfig.customUserVars && typeof serverConfig.customUserVars === 'object') {
for (const varName of Object.keys(serverConfig.customUserVars)) {
try {
const value = await getUserPluginAuthValue(user.id, varName, false, pluginKey);
authValueFlags[varName] = !!(value && value.length > 0);
} catch (err) {
logger.error(
`[MCP Auth Value Flags] Error checking ${varName} for user ${user.id}:`,
err,
);
authValueFlags[varName] = false;
}
}
}
res.json({
success: true,
serverName,
authValueFlags,
});
} catch (error) {
logger.error(
`[MCP Auth Value Flags] Failed to check auth value flags for ${req.params.serverName}`,
error,
);
res.status(500).json({ error: 'Failed to check auth value flags' });
}
});
async function getOAuthHeaders(serverName, userId, configServers) {
const serverConfig = await getMCPServersRegistry().getServerConfig(
serverName,
userId,
configServers,
);
return serverConfig?.oauth_headers ?? {};
}
/**
MCP Server CRUD Routes (User-Managed MCP Servers)
*/
/**
* Get list of accessible MCP servers
* @route GET /api/mcp/servers
* @param {Object} req.query - Query parameters for pagination and search
* @param {number} [req.query.limit] - Number of results per page
* @param {string} [req.query.after] - Pagination cursor
* @param {string} [req.query.search] - Search query for title/description
* @returns {MCPServerListResponse} 200 - Success response - application/json
*/
router.get('/servers', requireJwtAuth, checkMCPUsePermissions, getMCPServersList);
/**
* Create a new MCP server
* @route POST /api/mcp/servers
* @param {MCPServerCreateParams} req.body - The MCP server creation parameters.
* @returns {MCPServer} 201 - Success response - application/json
*/
router.post('/servers', requireJwtAuth, checkMCPCreate, createMCPServerController);
/**
* Get single MCP server by ID
* @route GET /api/mcp/servers/:serverName
* @param {string} req.params.serverName - MCP server identifier.
* @returns {MCPServer} 200 - Success response - application/json
*/
router.get(
'/servers/:serverName',
requireJwtAuth,
checkMCPUsePermissions,
canAccessMCPServerResource({
requiredPermission: PermissionBits.VIEW,
resourceIdParam: 'serverName',
}),
getMCPServerById,
);
/**
* Update MCP server
* @route PATCH /api/mcp/servers/:serverName
* @param {string} req.params.serverName - MCP server identifier.
* @param {MCPServerUpdateParams} req.body - The MCP server update parameters.
* @returns {MCPServer} 200 - Success response - application/json
*/
router.patch(
'/servers/:serverName',
requireJwtAuth,
checkMCPCreate,
canAccessMCPServerResource({
requiredPermission: PermissionBits.EDIT,
resourceIdParam: 'serverName',
}),
updateMCPServerController,
);
/**
* Delete MCP server
* @route DELETE /api/mcp/servers/:serverName
* @param {string} req.params.serverName - MCP server identifier.
* @returns {Object} 200 - Success response - application/json
*/
router.delete(
'/servers/:serverName',
requireJwtAuth,
checkMCPCreate,
canAccessMCPServerResource({
requiredPermission: PermissionBits.DELETE,
resourceIdParam: 'serverName',
}),
(req, res) => deleteMCPServerController(req, res, maybeUninstallOAuthMCP),
);
module.exports = router;