Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🥊 test: Prove MCP Refresh Coordination Across Replica Processes (#16131)

lia-by-librechat[bot]1ff694b3985b
diff --git a/packages/api/src/mcp/__tests__/MCPOAuthMultiProcess.integration.test.ts b/packages/api/src/mcp/__tests__/MCPOAuthMultiProcess.integration.test.ts
new file mode 100644
index 0000000000..373bd7a626
--- /dev/null
+++ b/packages/api/src/mcp/__tests__/MCPOAuthMultiProcess.integration.test.ts
@@ -0,0 +1,445 @@
+/**
+ * MCP OAuth guarantees that only a multi-process deployment can establish.
+ *
+ * Existing coverage runs two instances inside one Jest process, where a process-local single-flight
+ * map can satisfy an assertion production cannot: real replicas share only Redis, Mongo and the
+ * provider. These tests therefore fork REAL worker processes (`helpers/mcpOAuthWorkerBoot.cjs`) that
+ * use the production adapters, and assert the outcomes a user experiences: one redemption per
+ * rotation, an adopted result on the peer, and recovery after a replica dies.
+ *
+ * The negative control matters as much as the positive one. With coordination disabled the same
+ * harness must produce TWO redemptions while the provider holds the first response open; without
+ * that, a passing coordinated run could simply mean the workers never overlapped.
+ */
+
+import path from 'path';
+import mongoose from 'mongoose';
+import { randomUUID } from 'crypto';
+import { fork } from 'child_process';
+import { MongoMemoryServer } from 'mongodb-memory-server';
+import type { ChildProcess } from 'child_process';
+import type { OAuthTestServer } from './helpers/oauthTestServer';
+import { createOAuthMCPServer } from './helpers/oauthTestServer';
+
+const WORKER_BOOT = path.join(__dirname, 'helpers', 'mcpOAuthWorkerBoot.cjs');
+const CLIENT_ID = 'librechat-multiprocess-harness';
+/** Test-only material; the worker encrypts with the production helpers, which require both. */
+const CREDS_KEY = 'a'.repeat(64);
+const CREDS_IV = 'b'.repeat(32);
+const BOOT_TIMEOUT_MS = 60_000;
+const SETTLE_MS = 750;
+
+interface WorkerReply {
+ id: number;
+ ok: boolean;
+ result?: unknown;
+ /** Errors cross IPC as plain data; Error instances do not survive structured cloning. */
+ error?: { name?: string; message?: string; stack?: string };
+}
+
+interface TokenOutcome {
+ obtained: boolean;
+ /** Which side of the coordination this replica took, from `getTokens`' own hooks. */
+ role: 'refreshed' | 'adopted' | null;
+ expiredAtEntry?: boolean;
+ resourceStatus: number | null;
+ refreshDigest: string | null;
+ credentialSetId?: string | null;
+}
+
+/** One replica: a real child process speaking a small request/response protocol over IPC. */
+class ReplicaProcess {
+ private readonly pending = new Map<
+ number,
+ { resolve: (value: unknown) => void; reject: (error: Error) => void }
+ >();
+
+ private nextId = 1;
+ private exited = false;
+ /** Unsolicited worker notifications, used to establish overlap instead of assuming it. */
+ public readonly progress: string[] = [];
+
+ private constructor(
+ public readonly name: string,
+ private readonly child: ChildProcess,
+ private readonly stderr: string[],
+ ) {
+ child.on('message', (message) => {
+ const notification = message as { progress?: string };
+ if (notification.progress) {
+ this.progress.push(notification.progress);
+ return;
+ }
+ const reply = message as WorkerReply;
+ const waiter = this.pending.get(reply.id);
+ if (!waiter) {
+ return;
+ }
+ this.pending.delete(reply.id);
+ if (reply.ok) {
+ waiter.resolve(reply.result);
+ } else {
+ const failure = new Error(`[${name}] ${reply.error?.message ?? 'worker command failed'}`);
+ failure.name = reply.error?.name ?? 'Error';
+ if (reply.error?.stack) {
+ failure.stack = `${failure.name}: ${failure.message}\n${reply.error.stack}`;
+ }
+ waiter.reject(failure);
+ }
+ });
+ child.on('exit', (code, signal) => {
+ this.exited = true;
+ const reason = `[${name}] exited (code ${code ?? 'null'}, signal ${signal ?? 'null'})`;
+ for (const waiter of this.pending.values()) {
+ waiter.reject(new Error(reason));
+ }
+ this.pending.clear();
+ });
+ }
+
+ static async start(options: {
+ name: string;
+ mongoUri: string;
+ providerUrl: string;
+ userId: string;
+ serverName: string;
+ flowNamespace: string;
+ coordinate: boolean;
+ }): Promise<ReplicaProcess> {
+ const child = fork(WORKER_BOOT, [], {
+ stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+ env: {
+ ...process.env,
+ NODE_ENV: 'test',
+ USE_REDIS: 'true',
+ CREDS_KEY,
+ CREDS_IV,
+ MCP_TEST_MONGO_URI: options.mongoUri,
+ MCP_TEST_PROVIDER_URL: options.providerUrl,
+ MCP_TEST_USER_ID: options.userId,
+ MCP_TEST_SERVER_NAME: options.serverName,
+ MCP_TEST_CLIENT_ID: CLIENT_ID,
+ MCP_TEST_FLOW_NAMESPACE: options.flowNamespace,
+ MCP_TEST_COORDINATE: String(options.coordinate),
+ },
+ });
+
+ /** Keep worker stderr; silence is what makes a process harness hard to debug. */
+ const stderr: string[] = [];
+ child.stderr?.on('data', (chunk) => stderr.push(String(chunk)));
+ child.stdout?.resume();
+
+ const replica = new ReplicaProcess(options.name, child, stderr);
+ try {
+ await new Promise<void>((resolve, reject) => {
+ const timer = setTimeout(() => {
+ reject(
+ new Error(
+ `[${options.name}] not ready in ${BOOT_TIMEOUT_MS}ms. stderr: ${stderr.join('').slice(-2000)}`,
+ ),
+ );
+ }, BOOT_TIMEOUT_MS);
+ child.once('message', (message) => {
+ clearTimeout(timer);
+ if ((message as { ready?: boolean }).ready) {
+ resolve();
+ } else {
+ reject(
+ new Error(
+ `[${options.name}] failed to initialize: ${(message as { error?: { message?: string } }).error?.message ?? 'no ready signal'}`,
+ ),
+ );
+ }
+ });
+ child.once('exit', () => {
+ clearTimeout(timer);
+ reject(
+ new Error(
+ `[${options.name}] exited during boot. stderr: ${stderr.join('').slice(-2000)}`,
+ ),
+ );
+ });
+ });
+ } catch (error) {
+ /**
+ * A worker that never reported ready is still running, holding Mongo and Redis connections
+ * that would outlive this suite and interfere with the rest of the integration lane. Reap it
+ * before surfacing the boot failure.
+ */
+ await replica.kill();
+ throw error;
+ }
+ return replica;
+ }
+
+ send<T = unknown>(command: string, payload?: Record<string, unknown>): Promise<T> {
+ if (this.exited) {
+ return Promise.reject(new Error(`[${this.name}] is no longer running`));
+ }
+ const id = this.nextId++;
+ return new Promise<T>((resolve, reject) => {
+ this.pending.set(id, {
+ resolve: resolve as (value: unknown) => void,
+ reject,
+ });
+ this.child.send({ id, command, payload });
+ });
+ }
+
+ /** Terminates without shutdown, standing in for a replica that dies mid-operation. */
+ async kill(): Promise<void> {
+ if (this.exited) {
+ return;
+ }
+ const stopped = new Promise<void>((resolve) => this.child.once('exit', () => resolve()));
+ this.child.kill('SIGKILL');
+ await stopped;
+ }
+
+ async stop(): Promise<void> {
+ if (this.exited) {
+ return;
+ }
+ await this.send('shutdown').catch(() => undefined);
+ const stopped = new Promise<void>((resolve) => this.child.once('exit', () => resolve()));
+ this.child.kill('SIGTERM');
+ await stopped;
+ }
+}
+
+async function waitFor(
+ condition: () => boolean,
+ description: string,
+ timeoutMs = 20_000,
+): Promise<void> {
+ const deadline = Date.now() + timeoutMs;
+ while (!condition()) {
+ if (Date.now() > deadline) {
+ throw new Error(`Timed out waiting for ${description}`);
+ }
+ await new Promise((resolve) => setTimeout(resolve, 25));
+ }
+}
+
+const describeWithRedis = process.env.REDIS_URI ? describe : describe.skip;
+
+describeWithRedis('MCP OAuth credential lifecycle across separate replica processes', () => {
+ let mongod: MongoMemoryServer;
+ let server: OAuthTestServer;
+ const replicas: ReplicaProcess[] = [];
+ let holdRefresh = false;
+ let releaseRefresh: (() => void) | undefined;
+ let gatePromise: Promise<void> | undefined;
+
+ const refreshGrants = () =>
+ server.tokenRequests.filter((request) => request.grantType === 'refresh_token').length;
+ const consentGrants = () =>
+ server.tokenRequests.filter((request) => request.grantType === 'authorization_code').length;
+
+ beforeAll(async () => {
+ /**
+ * `--nounixsocket` keeps mongod off its hardcoded /tmp socket path, which a read-only root
+ * filesystem rejects with an opaque fassert failure. It changes nothing about the server.
+ */
+ mongod = await MongoMemoryServer.create({ instance: { args: ['--nounixsocket'] } });
+ }, BOOT_TIMEOUT_MS);
+
+ afterAll(async () => {
+ await mongod?.stop();
+ });
+
+ beforeEach(async () => {
+ holdRefresh = false;
+ gatePromise = new Promise<void>((resolve) => {
+ releaseRefresh = resolve;
+ });
+ server = await createOAuthMCPServer({
+ issueRefreshTokens: true,
+ rotateRefreshTokens: true,
+ refreshGate: () => (holdRefresh ? gatePromise : undefined),
+ });
+ });
+
+ afterEach(async () => {
+ releaseRefresh?.();
+ await Promise.all(replicas.splice(0).map((replica) => replica.stop()));
+ await server?.close();
+ });
+
+ /** Each scenario owns its principal, server name and flow namespace, so state never bleeds. */
+ const scenario = () => {
+ const suffix = randomUUID().slice(0, 8);
+ return {
+ userId: new mongoose.Types.ObjectId().toString(),
+ serverName: `multiprocess-server-${suffix}`,
+ flowNamespace: `MCPOAuthMultiProcess-${process.pid}-${suffix}`,
+ };
+ };
+
+ const startReplica = async (
+ name: string,
+ context: ReturnType<typeof scenario>,
+ coordinate: boolean,
+ ): Promise<ReplicaProcess> => {
+ const replica = await ReplicaProcess.start({
+ name,
+ mongoUri: mongod.getUri(),
+ providerUrl: server.url,
+ coordinate,
+ ...context,
+ });
+ replicas.push(replica);
+ return replica;
+ };
+
+ it(
+ 'redeems a rotating refresh token once when both replicas refresh together',
+ async () => {
+ const context = scenario();
+ const [replicaA, replicaB] = await Promise.all([
+ startReplica('replica-A', context, true),
+ startReplica('replica-B', context, true),
+ ]);
+
+ await replicaA.send('authorize');
+ await replicaA.send('expireAccess');
+ expect(consentGrants()).toBe(1);
+
+ /** Hold the provider's response so the two reads genuinely overlap. */
+ holdRefresh = true;
+ const readA = replicaA.send<TokenOutcome>('getTokens');
+ const readB = replicaB.send<TokenOutcome>('getTokens');
+
+ /**
+ * Establish the overlap before releasing anything. Waiting only for a provider hit would let
+ * a slow peer arrive after the winner had already persisted, read a fresh credential, and
+ * never contend: the redemption count would still be 1 and the assertion would pass while
+ * proving nothing. Both replicas must have entered the refresh path on an expired credential.
+ */
+ await waitFor(() => refreshGrants() >= 1, 'the first replica to reach the provider');
+ await waitFor(
+ () => replicaA.progress.includes('entered-refresh-path'),
+ 'replica A to enter the refresh path',
+ );
+ await waitFor(
+ () => replicaB.progress.includes('entered-refresh-path'),
+ 'replica B to enter the refresh path',
+ );
+ /** The peer must wait for the winner, not start a second redemption of the same token. */
+ await new Promise((resolve) => setTimeout(resolve, SETTLE_MS));
+ expect(refreshGrants()).toBe(1);
+
+ releaseRefresh?.();
+ const [outcomeA, outcomeB] = await Promise.all([readA, readB]);
+
+ expect(outcomeA.obtained).toBe(true);
+ expect(outcomeB.obtained).toBe(true);
+ /** Both saw an expired credential, so neither read was a cache hit on a fresh token. */
+ expect(outcomeA.expiredAtEntry).toBe(true);
+ expect(outcomeB.expiredAtEntry).toBe(true);
+ /**
+ * `getTokens` reports which side each replica took. Exactly one redeemed and the other
+ * adopted what it published: that pair is the coordination itself, and it cannot be produced
+ * by a replica that merely arrived late and loaded an already-valid credential.
+ */
+ expect([outcomeA.role, outcomeB.role].sort()).toEqual(['adopted', 'refreshed']);
+ /** Both replicas hold a credential the resource server accepts. */
+ expect(outcomeA.resourceStatus).toBe(200);
+ expect(outcomeB.resourceStatus).toBe(200);
+ /** Both converged on one rotated credential, and consent was never requested again. */
+ expect(outcomeB.refreshDigest).toBe(outcomeA.refreshDigest);
+ expect(refreshGrants()).toBe(1);
+ expect(consentGrants()).toBe(1);
+
+ /**
+ * The rotation that was actually persisted has to be the one the provider now expects, so a
+ * later cycle must succeed. A lost replacement would only surface here.
+ */
+ await replicaB.send('expireAccess');
+ const nextCycle = await replicaB.send<TokenOutcome>('getTokens');
+ expect(nextCycle.obtained).toBe(true);
+ expect(nextCycle.resourceStatus).toBe(200);
+ expect(nextCycle.refreshDigest).not.toBe(outcomeA.refreshDigest);
+ expect(refreshGrants()).toBe(2);
+ expect(consentGrants()).toBe(1);
+ },
+ BOOT_TIMEOUT_MS * 2,
+ );
+
+ it(
+ 'observes two redemptions without coordination, proving the replicas truly overlap',
+ async () => {
+ const context = scenario();
+ const [replicaA, replicaB] = await Promise.all([
+ startReplica('replica-A', context, false),
+ startReplica('replica-B', context, false),
+ ]);
+
+ await replicaA.send('authorize');
+ await replicaA.send('expireAccess');
+
+ holdRefresh = true;
+ const readA = replicaA.send<TokenOutcome>('getTokens').catch(() => null);
+ const readB = replicaB.send<TokenOutcome>('getTokens').catch(() => null);
+
+ /**
+ * This is the control for the test above: uncoordinated replicas reach the provider twice
+ * while the first response is still open. If this ever stops happening, the coordinated
+ * assertion is no longer evidence of coordination.
+ */
+ await waitFor(
+ () => replicaA.progress.includes('entered-refresh-path'),
+ 'replica A to enter the refresh path',
+ );
+ await waitFor(
+ () => replicaB.progress.includes('entered-refresh-path'),
+ 'replica B to enter the refresh path',
+ );
+ await waitFor(
+ () => refreshGrants() >= 2,
+ 'both uncoordinated replicas to reach the provider',
+ );
+ expect(refreshGrants()).toBe(2);
+
+ releaseRefresh?.();
+ await Promise.all([readA, readB]);
+ },
+ BOOT_TIMEOUT_MS * 2,
+ );
+
+ it(
+ 'recovers on a replacement replica after the authorizing replica is killed',
+ async () => {
+ const context = scenario();
+ const original = await startReplica('replica-original', context, true);
+
+ await original.send('authorize');
+ await original.send('expireAccess');
+ const rotated = await original.send<TokenOutcome>('getTokens');
+ expect(rotated.obtained).toBe(true);
+ expect(refreshGrants()).toBe(1);
+
+ /** No graceful shutdown: nothing in memory survives, only what was persisted. */
+ await original.kill();
+
+ const replacement = await startReplica('replica-replacement', context, true);
+ /** The durable claim: credentials outlived the process that obtained them. */
+ const restored = await replacement.send<TokenOutcome & { hasClient: boolean }>('readStored');
+ expect(restored.obtained).toBe(true);
+ expect(restored.hasClient).toBe(true);
+ expect(restored.refreshDigest).toEqual(expect.any(String));
+ expect(restored.credentialSetId).toEqual(expect.any(String));
+
+ await replacement.send('expireAccess');
+ const afterRestart = await replacement.send<TokenOutcome>('getTokens');
+
+ /** Recovery came from durable credentials alone: still one consent for the whole scenario. */
+ expect(afterRestart.obtained).toBe(true);
+ expect(afterRestart.resourceStatus).toBe(200);
+ expect(afterRestart.refreshDigest).not.toBe(rotated.refreshDigest);
+ expect(refreshGrants()).toBe(2);
+ expect(consentGrants()).toBe(1);
+ },
+ BOOT_TIMEOUT_MS * 2,
+ );
+});
diff --git a/packages/api/src/mcp/__tests__/helpers/mcpOAuthWorkerBoot.cjs b/packages/api/src/mcp/__tests__/helpers/mcpOAuthWorkerBoot.cjs
new file mode 100644
index 0000000000..b3a2172ec9
--- /dev/null
+++ b/packages/api/src/mcp/__tests__/helpers/mcpOAuthWorkerBoot.cjs
@@ -0,0 +1,32 @@
+'use strict';
+
+/**
+ * Bootstrap for the MCP OAuth multi-process harness.
+ *
+ * The worker must be a REAL separate process, not a second in-process instance: process-local
+ * single-flight maps, connection caches and module state would otherwise satisfy a cross-replica
+ * assertion that production cannot satisfy. Jest's transform is unavailable outside the test
+ * process, so compile the TypeScript worker with ts-node and resolve the package's `~/*` alias
+ * the same way tsconfig.json declares it.
+ *
+ * Nothing here fakes a production adapter. Mongo, Redis, encryption and the OAuth handler are the
+ * real implementations; only the provider and the stores are test-owned.
+ */
+
+const path = require('path');
+
+const apiRoot = path.resolve(__dirname, '../../../..');
+
+require('ts-node').register({
+ transpileOnly: true,
+ esm: false,
+ project: path.join(apiRoot, 'tsconfig.json'),
+ compilerOptions: { module: 'commonjs', moduleResolution: 'node' },
+});
+
+require('tsconfig-paths').register({
+ baseUrl: apiRoot,
+ paths: { '~/*': ['./src/*'] },
+});
+
+require('./mcpOAuthWorkerMain.ts');
diff --git a/packages/api/src/mcp/__tests__/helpers/mcpOAuthWorkerMain.ts b/packages/api/src/mcp/__tests__/helpers/mcpOAuthWorkerMain.ts
new file mode 100644
index 0000000000..e17815df00
--- /dev/null
+++ b/packages/api/src/mcp/__tests__/helpers/mcpOAuthWorkerMain.ts
@@ -0,0 +1,334 @@
+/**
+ * One replica of the MCP OAuth multi-process harness.
+ *
+ * Runs in its own process with production adapters: a real Mongo connection and the real token
+ * methods (so credentials are encrypted and persisted exactly as deployed), a real Redis-backed
+ * `FlowStateManager` (so refresh coordination and the persistence fence are distributed rather
+ * than process-local), and the real `MCPTokenStorage` / `MCPOAuthHandler`. Only the OAuth provider
+ * and the stores are test-owned.
+ *
+ * Secrets never leave this process: the parent receives digests and HTTP statuses, never a token.
+ */
+
+import mongoose from 'mongoose';
+import { createHash } from 'crypto';
+import { createMethods, createModels, decryptV2 } from '@librechat/data-schemas';
+import type { TokenMethods } from '@librechat/data-schemas';
+import type {
+ MCPOAuthTokens,
+ OAuthClientInformation,
+ OAuthStoredClientMetadata,
+} from '~/mcp/oauth';
+import { MCPOAuthHandler, MCPTokenStorage } from '~/mcp/oauth';
+import { standardCache } from '~/cache/cacheFactory';
+import { FlowStateManager } from '~/flow/manager';
+
+interface WorkerRequest {
+ id: number;
+ command: string;
+ payload?: Record<string, unknown>;
+}
+
+const env = (name: string): string => {
+ const value = process.env[name];
+ if (!value) {
+ throw new Error(`Worker requires ${name}`);
+ }
+ return value;
+};
+
+const providerUrl = env('MCP_TEST_PROVIDER_URL');
+const userId = env('MCP_TEST_USER_ID');
+const serverName = env('MCP_TEST_SERVER_NAME');
+const clientId = env('MCP_TEST_CLIENT_ID');
+const flowNamespace = env('MCP_TEST_FLOW_NAMESPACE');
+const coordinateRefresh = process.env.MCP_TEST_COORDINATE === 'true';
+/** The provider listens on loopback, which the SSRF gate blocks unless explicitly allowed. */
+const allowedAddresses = [new URL(providerUrl).host];
+const identifier = `mcp:${serverName}`;
+
+let tokenMethods: TokenMethods;
+let flowManager: FlowStateManager<MCPOAuthTokens | null>;
+
+/** Digest so the parent can compare rotation without a credential crossing the IPC channel. */
+const digest = (value: string): string =>
+ createHash('sha256').update(value).digest('hex').slice(0, 16);
+
+const clientInfo: OAuthClientInformation = {
+ client_id: clientId,
+ redirect_uris: ['http://localhost'],
+ grant_types: ['authorization_code', 'refresh_token'],
+ response_types: ['code'],
+ token_endpoint_auth_method: 'none',
+};
+
+const storedMetadata = (): OAuthStoredClientMetadata =>
+ ({
+ issuer: providerUrl.replace(/\/$/, ''),
+ authorization_endpoint: new URL('authorize', providerUrl).href,
+ token_endpoint: new URL('token', providerUrl).href,
+ response_types_supported: ['code'],
+ grant_types_supported: ['authorization_code', 'refresh_token'],
+ token_endpoint_auth_methods_supported: ['none'],
+ server_url: providerUrl,
+ client_source: 'dynamic',
+ }) as OAuthStoredClientMetadata;
+
+async function init(): Promise<void> {
+ createModels(mongoose);
+ tokenMethods = createMethods(mongoose) as unknown as TokenMethods;
+ await mongoose.connect(env('MCP_TEST_MONGO_URI'), { autoIndex: false });
+ flowManager = new FlowStateManager<MCPOAuthTokens | null>(standardCache(flowNamespace, 60_000), {
+ ttl: 60_000,
+ });
+}
+
+/** Completes a real authorization-code grant against the provider. */
+async function exchangeAuthorizationCode(): Promise<MCPOAuthTokens> {
+ const authUrl = new URL('authorize', providerUrl);
+ authUrl.searchParams.set('redirect_uri', 'http://localhost');
+ authUrl.searchParams.set('state', `multiprocess-${process.pid}`);
+ authUrl.searchParams.set('client_id', clientId);
+
+ const authResponse = await fetch(authUrl, { redirect: 'manual' });
+ const location = authResponse.headers.get('location');
+ if (!location) {
+ throw new Error(`Authorization failed with HTTP ${authResponse.status}`);
+ }
+ const code = new URL(location).searchParams.get('code');
+ if (!code) {
+ throw new Error('Authorization response carried no code');
+ }
+
+ const tokenResponse = await fetch(new URL('token', providerUrl), {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+ body: new URLSearchParams({
+ grant_type: 'authorization_code',
+ code,
+ client_id: clientId,
+ }),
+ });
+ if (!tokenResponse.ok) {
+ throw new Error(`Token exchange failed with HTTP ${tokenResponse.status}`);
+ }
+ const body = (await tokenResponse.json()) as {
+ access_token: string;
+ token_type: string;
+ expires_in: number;
+ refresh_token?: string;
+ };
+ return {
+ ...body,
+ obtained_at: Date.now(),
+ expires_at: Date.now() + body.expires_in * 1000,
+ } as MCPOAuthTokens;
+}
+
+/** Proves a credential is accepted by the protected resource, without revealing it. */
+async function probeResource(accessToken: string): Promise<number> {
+ const response = await fetch(providerUrl, {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/json',
+ Accept: 'application/json, text/event-stream',
+ Authorization: `Bearer ${accessToken}`,
+ },
+ body: JSON.stringify({
+ jsonrpc: '2.0',
+ id: 1,
+ method: 'initialize',
+ params: {
+ protocolVersion: '2025-03-26',
+ capabilities: {},
+ clientInfo: { name: 'multiprocess-harness', version: '0.0.1' },
+ },
+ }),
+ });
+ return response.status;
+}
+
+/** Token metadata is a Mongoose Map on a hydrated document and a plain object once lean. */
+function readCredentialSetId(record: { metadata?: unknown } | null): string | null {
+ const metadata = record?.metadata as Map<string, unknown> | Record<string, unknown> | undefined;
+ if (!metadata) {
+ return null;
+ }
+ const value =
+ metadata instanceof Map
+ ? metadata.get('credential_set_id')
+ : (metadata as Record<string, unknown>).credential_set_id;
+ return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+/** Digest of the persisted refresh credential, so the parent can observe rotation. */
+async function storedRefreshDigest(): Promise<string | null> {
+ const record = await tokenMethods.findToken({
+ userId,
+ type: 'mcp_oauth_refresh',
+ identifier: `${identifier}:refresh`,
+ });
+ return record ? digest(await decryptV2(record.token)) : null;
+}
+
+const commands: Record<string, (payload: Record<string, unknown>) => Promise<unknown>> = {
+ /** Interactive authorization, persisted through the production storage path. */
+ async authorize() {
+ const tokens = await exchangeAuthorizationCode();
+ const stored = await MCPTokenStorage.storeTokens({
+ userId,
+ serverName,
+ tokens,
+ createToken: tokenMethods.createToken,
+ updateToken: tokenMethods.updateToken,
+ deleteTokens: tokenMethods.deleteTokens,
+ findToken: tokenMethods.findToken,
+ clientInfo,
+ metadata: storedMetadata(),
+ flowManager,
+ });
+ return { credentialSetId: stored.credential_set_id };
+ },
+
+ /** Ages the stored access record so the next read must refresh, as elapsed time would. */
+ async expireAccess() {
+ await tokenMethods.updateToken({ userId, type: 'mcp_oauth', identifier }, { expiresIn: -60 });
+ return { expired: true };
+ },
+
+ /** The production read path: refresh when expired, coordinating across replicas. */
+ async getTokens() {
+ /**
+ * Confirm the credential this replica is about to read is actually expired, then tell the
+ * parent. A concurrency assertion that only counts provider hits can pass vacuously when one
+ * replica arrives after the winner already persisted: it would simply load a fresh token and
+ * never contend. The parent waits for this signal from BOTH replicas before releasing the
+ * provider, so the overlap is established rather than assumed from a fixed delay.
+ */
+ const accessBefore = await tokenMethods.findToken({ userId, type: 'mcp_oauth', identifier });
+ const expiredAtEntry =
+ accessBefore?.expiresAt != null && new Date() >= new Date(accessBefore.expiresAt);
+ process.send?.({ progress: 'entered-refresh-path', expiredAtEntry });
+
+ /**
+ * `getTokens` invokes exactly one of these per call, so they report which side of the
+ * coordination this replica took: the redeemer, or a peer adopting what the redeemer
+ * published. Asserting the pair is what makes the test non-vacuous regardless of timing.
+ */
+ let role: 'refreshed' | 'adopted' | null = null;
+
+ const tokens = await MCPTokenStorage.getTokens({
+ userId,
+ serverName,
+ onRefreshSuccess: async () => {
+ role = 'refreshed';
+ },
+ onTokensAdopted: async () => {
+ role = 'adopted';
+ },
+ findToken: tokenMethods.findToken,
+ createToken: tokenMethods.createToken,
+ updateToken: tokenMethods.updateToken,
+ deleteTokens: tokenMethods.deleteTokens,
+ coordinateRefresh,
+ flowManager,
+ refreshTokens: async (refreshToken, metadata, signal) =>
+ MCPOAuthHandler.refreshOAuthTokens(
+ refreshToken,
+ {
+ serverName: metadata.serverName,
+ serverUrl: metadata.storedServerUrl ?? providerUrl,
+ clientInfo: metadata.clientInfo,
+ storedTokenEndpoint: metadata.storedTokenEndpoint,
+ storedAuthMethods: metadata.storedAuthMethods,
+ storedServerUrl: metadata.storedServerUrl,
+ clientSource: metadata.clientSource,
+ resource: metadata.resource,
+ },
+ {},
+ undefined,
+ null,
+ allowedAddresses,
+ signal,
+ ),
+ });
+ if (!tokens) {
+ return {
+ obtained: false,
+ role,
+ expiredAtEntry,
+ resourceStatus: null,
+ refreshDigest: await storedRefreshDigest(),
+ };
+ }
+ return {
+ obtained: true,
+ role,
+ expiredAtEntry,
+ accessDigest: digest(tokens.access_token),
+ credentialSetId: tokens.credential_set_id ?? null,
+ /** Proves the credential is accepted by the protected resource, not merely non-null. */
+ resourceStatus: await probeResource(tokens.access_token),
+ refreshDigest: await storedRefreshDigest(),
+ };
+ },
+
+ /** Persisted-state digests, so the parent can assert rotation and survival. */
+ async readStored() {
+ const [access, refresh, client] = await Promise.all([
+ tokenMethods.findToken({ userId, type: 'mcp_oauth', identifier }),
+ tokenMethods.findToken({
+ userId,
+ type: 'mcp_oauth_refresh',
+ identifier: `${identifier}:refresh`,
+ }),
+ tokenMethods.findToken({
+ userId,
+ type: 'mcp_oauth_client',
+ identifier: `${identifier}:client`,
+ }),
+ ]);
+ return {
+ obtained: access != null,
+ accessDigest: access ? digest(await decryptV2(access.token)) : null,
+ refreshDigest: refresh ? digest(await decryptV2(refresh.token)) : null,
+ credentialSetId: readCredentialSetId(access) ?? readCredentialSetId(client),
+ hasClient: client != null,
+ role: null,
+ resourceStatus: null,
+ };
+ },
+};
+
+process.on('message', (raw: unknown) => {
+ const request = raw as WorkerRequest;
+ void (async () => {
+ try {
+ const handler = commands[request.command];
+ if (!handler) {
+ throw new Error(`Unknown worker command: ${request.command}`);
+ }
+ const result = await handler(request.payload ?? {});
+ process.send?.({ id: request.id, ok: true, result });
+ } catch (error) {
+ process.send?.({
+ id: request.id,
+ ok: false,
+ error: {
+ name: error instanceof Error ? error.name : 'Error',
+ message: error instanceof Error ? error.message : String(error),
+ stack: error instanceof Error ? error.stack : undefined,
+ },
+ });
+ }
+ })();
+});
+
+void init().then(
+ () => process.send?.({ ready: true, pid: process.pid }),
+ (error: unknown) =>
+ process.send?.({
+ ready: false,
+ error: { message: error instanceof Error ? error.message : String(error) },
+ }),
+);
diff --git a/packages/api/src/mcp/__tests__/helpers/oauthTestServer.ts b/packages/api/src/mcp/__tests__/helpers/oauthTestServer.ts
index 5975b678c3..3956ea2fa9 100644
--- a/packages/api/src/mcp/__tests__/helpers/oauthTestServer.ts
+++ b/packages/api/src/mcp/__tests__/helpers/oauthTestServer.ts
@@ -74,6 +74,11 @@ export interface OAuthTestServerOptions {
rejectRefreshTokens?: number;
/** Injects an endpoint failure before redemption; undefined resumes normal refresh behavior. */
refreshFailure?: () => { status: number; body: string } | undefined;
+ /**
+ * Awaited after a refresh grant is recorded but before it is redeemed, so a test can hold
+ * concurrent refreshes open and observe how many redemptions the callers actually attempt.
+ */
+ refreshGate?: () => Promise<void> | undefined;
/** Optional test hook for controlling echo-tool completion. */
echoHandler?: (message: string) => string | Promise<string>;
}
@@ -145,6 +150,7 @@ export async function createOAuthMCPServer(
rejectRefreshTokens = 0,
echoHandler,
refreshFailure,
+ refreshGate,
} = options;
const sessions = new Map<string, StreamableHTTPServerTransport>();
@@ -400,6 +406,7 @@ export async function createOAuthMCPServer(
}
if (grantType === 'refresh_token' && issueRefreshTokens) {
+ await refreshGate?.();
const failure = refreshFailure?.();
if (failure) {
res.writeHead(failure.status, { 'Content-Type': 'application/json' });