Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

feat: implement per-request timeout for MCP OAuth HTTP calls (#134)

Sujai Kumar Guptadbd2f8d3c321
diff --git a/packages/server/src/apis/mcpServers.ts b/packages/server/src/apis/mcpServers.ts
index 12a4073df..e7cec804f 100644
--- a/packages/server/src/apis/mcpServers.ts
+++ b/packages/server/src/apis/mcpServers.ts
@@ -1,21 +1,14 @@
import { OpenAPIHono, type RouteHandler } from '@hono/zod-openapi';
-import {
- extractErrorLogFields,
- isAuthRequired,
- McpConnectionError,
- McpDcrConfigurationError,
- RemoteMCP,
- withTimeout,
-} from '@truefoundry/utils-core/core';
+import { extractErrorLogFields, isAuthRequired, McpConnectionError, RemoteMCP } from '@truefoundry/utils-core/core';
import type { Logger } from 'winston';
import type { ResolveUserContext } from '../auth/identity';
import type { McpCatalog } from '../catalog/McpCatalog';
import configuration from '../config';
import type { IMcpServerStore, McpServerRecord } from '../db/mcpServerStore';
import type { WithTransaction } from '../db/transaction';
-import { ensureMcpClientRegistered, isMcpAuthRequired, resolveMcpAuth } from '../mcp/auth/mcpDcr';
-import { validateRedirectUris } from '../mcp/auth/mcpOAuthHelpers';
-import type { IOAuthTokenStore, OAuthToken } from '../mcp/auth/types';
+import { createMcpOAuthClient, isMcpAuthRequired, resolveMcpAuth } from '../mcp/auth/mcpDcr';
+import { mcpOAuthCallbackUrl, validateRedirectUris } from '../mcp/auth/mcpOAuthHelpers';
+import type { IOAuthTokenStore, OAuthClientRecord, OAuthToken } from '../mcp/auth/types';
import {
authorizeMcpServerRoute,
deleteMcpServerAuthRoute,
@@ -31,9 +24,6 @@ import type { ConfiguredMcpServer, McpAuthStatus, McpServerManifest, McpServerRe
import { resolveMcpAuthStatus } from '../schemas/mcpServer';
import { TENANT_ID } from './sessions';
-/** Registering a DCR OAuth client hits the MCP server's authorization server, so bound that call. */
-export const MCP_DCR_REGISTRATION_TIMEOUT_MS = 10_000;
-
export interface SettingsMcpServersRouterDeps<TTransaction> {
mcpCatalog: McpCatalog;
mcpServerStore: IMcpServerStore<TTransaction>;
@@ -102,28 +92,8 @@ function toMcpServerReadEntry({
};
}
-/** Admin/settings MCP CRUD (mounted at /api/v1/settings/mcp-servers).
- * TODO: Remove the server via txn if DCR fails to register
- */
+/** Admin/settings MCP CRUD (mounted at /api/v1/settings/mcp-servers). */
export function createSettingsMcpServersRouter<TTransaction>(deps: SettingsMcpServersRouterDeps<TTransaction>) {
- const registerDcrClient = async (params: {
- serverId: string;
- mcpServerUrl: string;
- mcpServerName: string;
- }): Promise<void> => {
- await withTimeout(
- ensureMcpClientRegistered({
- mcpServerStore: deps.mcpServerStore,
- serverId: params.serverId,
- mcpServerUrl: params.mcpServerUrl,
- mcpServerName: params.mcpServerName,
- clientName: configuration.MCP_DCR_OAUTH_CLIENT_NAME,
- }),
- MCP_DCR_REGISTRATION_TIMEOUT_MS,
- `DCR client registration for MCP server "${params.mcpServerName}"`,
- );
- };
-
const catalogHandler: RouteHandler<typeof getMcpServerCatalogRoute> = c => {
return c.json({ data: [...deps.mcpCatalog.list()] }, 200);
};
@@ -157,36 +127,58 @@ export function createSettingsMcpServersRouter<TTransaction>(deps: SettingsMcpSe
const putHandler: RouteHandler<typeof putMcpServerRoute> = async c => {
const userRef = deps.resolveUserContext(c).userRef;
const manifest: McpServerManifest = c.req.valid('json');
- const record = await deps.mcpServerStore.upsertServer({
- tenant_id: TENANT_ID,
- name: manifest.name,
- manifest,
- });
- if (record.manifest.auth?.type === 'dcr') {
- try {
- await registerDcrClient({
- serverId: record.id,
- mcpServerUrl: record.manifest.url,
- mcpServerName: record.manifest.name,
- });
- } catch (error) {
- // Permanent config error (server advertises no DCR support): a retry can never succeed, so
- // surface it now as a 422 for immediate feedback instead of a silently-broken server.
- if (error instanceof McpDcrConfigurationError) {
+
+ // DCR HTTP must finish before the txn so a failed registration never leaves a half-written row
+ // (txn cannot roll back the AS, and AGENTS forbids remote I/O inside withTransaction).
+ // Per-request OAuth timeouts live on mcpOAuthFetch (MCP_OAUTH_HTTP_TIMEOUT_MS) — no outer
+ // withTimeout, so hung AS failures surface as TimeoutError with the intended message.
+ let dcrClientToSave: OAuthClientRecord | undefined;
+ if (manifest.auth?.type === 'dcr') {
+ const prior = await deps.mcpServerStore.getServer({ tenant_id: TENANT_ID, name: manifest.name });
+ const existingClient = prior !== undefined ? await deps.mcpServerStore.getClient({ id: prior.id }) : undefined;
+ // Register when: brand-new server, client was cleared (e.g. invalid_client), or MCP URL changed
+ // (resource/AS may differ; reuse would keep stale oauth_server/client for the old AS).
+ // TODO: make manifest URL immutable after create so re-DCR / stale OAuth tokens are not possible via PUT.
+ const urlChanged = prior !== undefined && prior.manifest.url !== manifest.url;
+ const needsDcr = existingClient === undefined || urlChanged;
+ if (needsDcr) {
+ try {
+ dcrClientToSave = await createMcpOAuthClient({
+ mcpServerUrl: manifest.url,
+ mcpServerName: manifest.name,
+ redirectUri: mcpOAuthCallbackUrl(),
+ clientName: configuration.MCP_DCR_OAUTH_CLIENT_NAME,
+ });
+ } catch (error) {
deps.logger.error(
- `DCR misconfiguration for "${record.manifest.name}"; rejecting upsert`,
+ `DCR client registration failed for "${manifest.name}"; rejecting upsert`,
extractErrorLogFields(error),
);
- return c.json({ error: { message: error.message } }, 422);
+ const message =
+ error instanceof Error ? error.message : 'Failed to register OAuth client for this MCP server';
+ return c.json({ error: { message } }, 422);
}
- // Transient (network / timeout / flaky authorization server): keep the saved server and let
- // the next authorize retry, rather than failing the upsert on a temporary fault.
- deps.logger.warn(
- `Eager DCR client registration failed for "${record.manifest.name}"; will retry on authorize`,
- extractErrorLogFields(error),
- );
}
}
+
+ const record = await deps.withTransaction(async transaction => {
+ const saved = await deps.mcpServerStore.upsertServer(
+ {
+ tenant_id: TENANT_ID,
+ name: manifest.name,
+ manifest,
+ },
+ transaction,
+ );
+ if (dcrClientToSave !== undefined) {
+ // New DCR registration (create, missing client, or URL change): replace the shared client only.
+ // Existing per-user tokens are left in place; resolve/refresh fails them if they no longer
+ // match the new resource/AS, and users re-authorize from there.
+ await deps.mcpServerStore.saveClient({ id: saved.id, record: dcrClientToSave }, transaction);
+ }
+ return saved;
+ });
+
// A re-upsert preserves `id`, so a DCR server may already carry a token from a prior authorize.
const token =
record.manifest.auth?.type === 'dcr' ? await deps.tokenStore.getToken({ id: record.id, userRef }) : undefined;
diff --git a/packages/server/src/mcp/auth/mcpDcr.ts b/packages/server/src/mcp/auth/mcpDcr.ts
index 912ebb14b..c98a61ceb 100644
--- a/packages/server/src/mcp/auth/mcpDcr.ts
+++ b/packages/server/src/mcp/auth/mcpDcr.ts
@@ -12,6 +12,7 @@ import type {
OAuthClientMetadata,
OAuthTokens,
} from '@modelcontextprotocol/sdk/shared/auth.js';
+import type { FetchLike } from '@modelcontextprotocol/sdk/shared/transport.js';
import { McpConnectionError, McpDcrConfigurationError } from '@truefoundry/utils-core/core';
import { randomBytes } from 'node:crypto';
import type { WithTransaction } from '../../db/transaction';
@@ -32,6 +33,33 @@ import type {
ResolveMcpAuthResult,
} from './types';
+/** Per-request timeout for MCP OAuth discovery, DCR, and token HTTP calls. */
+export const MCP_OAUTH_HTTP_TIMEOUT_MS = 15_000;
+
+/**
+ * Abort hung authorization-server HTTP. Merges with any caller `signal` so both can cancel the request.
+ * Used by discoverOAuthServerInfo / registerClient / refreshAuthorization / exchangeAuthorization
+ * (startAuthorization is local PKCE + URL construction and never calls this).
+ */
+const mcpOAuthFetch: FetchLike = (url, init) => {
+ const timeoutSignal = AbortSignal.timeout(MCP_OAUTH_HTTP_TIMEOUT_MS);
+ const signal = init?.signal != null ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal;
+ return fetch(url, { ...init, signal });
+};
+
+function isTimeoutError(error: unknown): boolean {
+ return error instanceof Error && error.name === 'TimeoutError';
+}
+
+/** Same status as non-timeout faults; appends a timeout note so the API body is actionable. */
+function mcpOAuthConnectionError(message: string, error: unknown, statusCode: number): McpConnectionError {
+ let body = message;
+ if (isTimeoutError(error)) {
+ body = `${message}: timed out after ${String(MCP_OAUTH_HTTP_TIMEOUT_MS / 1000)}s waiting for the authorization server`;
+ }
+ return new McpConnectionError(body, statusCode, { cause: error });
+}
+
export function isMcpAuthRequired(result: ResolveMcpAuthResult): result is McpAuthRequiredResult {
return 'authUrl' in result;
}
@@ -51,22 +79,27 @@ async function registerMcpClientWithAuthMethodFallback(params: {
fullInfo = await registerClient(authorizationServerUrl, {
metadata,
clientMetadata: { ...clientMetadata, token_endpoint_auth_method: 'client_secret_post' },
+ fetchFn: mcpOAuthFetch,
});
} catch (firstError: unknown) {
if (!(firstError instanceof InvalidClientMetadataError)) {
- throw new McpConnectionError(
+ throw mcpOAuthConnectionError(
`Failed to dynamically register OAuth client for MCP server '${mcpServerName}'`,
+ firstError,
424,
- { cause: firstError instanceof Error ? firstError : undefined },
);
}
try {
- fullInfo = await registerClient(authorizationServerUrl, { metadata, clientMetadata });
+ fullInfo = await registerClient(authorizationServerUrl, {
+ metadata,
+ clientMetadata,
+ fetchFn: mcpOAuthFetch,
+ });
} catch (secondError: unknown) {
- throw new McpConnectionError(
+ throw mcpOAuthConnectionError(
`Failed to dynamically register OAuth client for MCP server '${mcpServerName}'`,
+ secondError,
424,
- { cause: secondError instanceof Error ? secondError : firstError },
);
}
}
@@ -96,7 +129,17 @@ export async function createMcpOAuthClient(params: {
clientName: string;
}): Promise<OAuthClientRecord> {
const { mcpServerUrl, mcpServerName, redirectUri, clientName } = params;
- const { authorizationServerUrl, authorizationServerMetadata: metadata } = await discoverOAuthServerInfo(mcpServerUrl);
+ let discovered: Awaited<ReturnType<typeof discoverOAuthServerInfo>>;
+ try {
+ discovered = await discoverOAuthServerInfo(mcpServerUrl, { fetchFn: mcpOAuthFetch });
+ } catch (error: unknown) {
+ throw mcpOAuthConnectionError(
+ `Failed to discover OAuth authorization server for MCP server '${mcpServerName}'`,
+ error,
+ 424,
+ );
+ }
+ const { authorizationServerUrl, authorizationServerMetadata: metadata } = discovered;
if (!metadata?.registration_endpoint) {
throw new McpDcrConfigurationError(
`MCP server '${mcpServerName}' has no DCR support (missing registration_endpoint); auth.type: dcr is misconfigured for this server`,
@@ -139,6 +182,7 @@ export async function ensureMcpClientRegistered(params: {
if (existing) {
return existing;
}
+ // Remote DCR finishes before any DB write so we never hold a connection during HTTP.
const client = await createMcpOAuthClient({
mcpServerUrl: params.mcpServerUrl,
mcpServerName: params.mcpServerName,
@@ -218,6 +262,7 @@ export async function resolveMcpAuth(params: {
clientInformation: mcpClientInformation(client.client),
refreshToken: token.refreshToken,
resource: resourceUrlFromServerUrl(params.mcpServerUrl),
+ fetchFn: mcpOAuthFetch,
});
const saved = oauthTokensToOAuthToken(refreshed, nowMs, token.refreshToken);
await params.tokenStore.saveToken({ ...tokenKey, token: saved });
@@ -278,6 +323,7 @@ export async function completeMcpAuthorization<TTransaction>(params: {
codeVerifier: pending.codeVerifier,
redirectUri: mcpOAuthCallbackUrl(),
resource: resourceUrlFromServerUrl(pending.mcpServerUrl),
+ fetchFn: mcpOAuthFetch,
});
} catch (error: unknown) {
if (error instanceof InvalidClientError) {
@@ -289,9 +335,7 @@ export async function completeMcpAuthorization<TTransaction>(params: {
cause: error,
});
}
- throw new McpConnectionError('OAuth token exchange failed', 400, {
- cause: error instanceof Error ? error : undefined,
- });
+ throw mcpOAuthConnectionError('OAuth token exchange failed', error, 400);
}
await params.tokenStore.saveToken({
id: pending.id,
diff --git a/packages/server/tests/unit/apis/mcpServers.test.ts b/packages/server/tests/unit/apis/mcpServers.test.ts
index 446004795..1e70e2ceb 100644
--- a/packages/server/tests/unit/apis/mcpServers.test.ts
+++ b/packages/server/tests/unit/apis/mcpServers.test.ts
@@ -50,8 +50,8 @@ describe('mcp-servers routers', () => {
const originalFetch = globalThis.fetch;
beforeAll(async () => {
- // Eager DCR registration dials the MCP server's authorization server. Fail that outbound call
- // fast so DCR upserts stay hermetic; the handler treats it as transient and still returns 200.
+ // Eager DCR dials the authorization server. Fail that outbound call fast so hermetic tests
+ // without an OAuth mock hit the "DCR before write" path and must not create rows.
globalThis.fetch = (async () => {
throw new Error('network disabled in tests');
}) as typeof fetch;
@@ -78,6 +78,30 @@ describe('mcp-servers routers', () => {
});
});
+ /** Persist a DCR server + stub client without calling the authorization server. */
+ async function seedDcrServerWithClient(body: typeof putBodyWithDcr = putBodyWithDcr) {
+ const record = await mcpServerStore.upsertServer({
+ tenant_id: TENANT_ID,
+ name: body.name,
+ manifest: body,
+ });
+ await mcpServerStore.saveClient({
+ id: record.id,
+ record: {
+ server: {
+ authorizationEndpoint: 'https://auth.example.com/authorize',
+ tokenEndpoint: 'https://auth.example.com/token',
+ codeChallengeMethodsSupported: ['S256'],
+ },
+ client: {
+ clientId: 'seed-client',
+ clientSecret: 'seed-secret',
+ },
+ },
+ });
+ return record;
+ }
+
afterAll(() => {
globalThis.fetch = originalFetch;
});
@@ -121,18 +145,19 @@ describe('mcp-servers routers', () => {
});
});
- it('PUT with DCR auth reports auth_required while no token is stored', async () => {
+ it('PUT with DCR fails registration without writing a server row', async () => {
const response = await settingsRouter.request('/', putInit(putBodyWithDcr));
- expect(response.status).toBe(200);
+ expect(response.status).toBe(422);
expect(await response.json()).toEqual({
- data: { ...putBodyWithDcr, auth_status: { status: 'auth_required' } },
+ error: {
+ message: "Failed to discover OAuth authorization server for MCP server 'linear'",
+ },
});
+ expect(await mcpServerStore.getServer({ tenant_id: TENANT_ID, name: putBodyWithDcr.name })).toBeUndefined();
});
it('DCR server reads authenticated when a token row exists, auth_required once deleted', async () => {
- await settingsRouter.request('/', putInit(putBodyWithDcr));
- const record = await mcpServerStore.getServer({ tenant_id: TENANT_ID, name: putBodyWithDcr.name });
- if (record === undefined) throw new Error('expected DCR server to exist');
+ const record = await seedDcrServerWithClient();
await tokenStore.saveToken({
id: record.id,
@@ -179,10 +204,8 @@ describe('mcp-servers routers', () => {
});
it('PUT re-upsert of a DCR server reports authenticated when a usable token already exists', async () => {
- // First upsert creates the row (no token yet) so we can key a token off its id.
- await settingsRouter.request('/', putInit(putBodyWithDcr));
- const record = await mcpServerStore.getServer({ tenant_id: TENANT_ID, name: putBodyWithDcr.name });
- if (record === undefined) throw new Error('expected DCR server to exist');
+ // Existing client skips DCR over the wire so network-disabled tests only exercise the DB path.
+ const record = await seedDcrServerWithClient();
await tokenStore.saveToken({
id: record.id,
@@ -205,6 +228,111 @@ describe('mcp-servers routers', () => {
await tokenStore.deleteToken({ id: record.id, userRef: LOCAL_USER_CONTEXT.userRef });
});
+ it('PUT URL change re-registers DCR and keeps existing tokens', async () => {
+ const record = await seedDcrServerWithClient();
+ await tokenStore.saveToken({
+ id: record.id,
+ userRef: LOCAL_USER_CONTEXT.userRef,
+ token: {
+ accessToken: 'stale-for-old-url',
+ refreshToken: 'stale-refresh',
+ expiresAt: '2099-01-01T00:00:00.000Z',
+ scope: null,
+ },
+ });
+
+ const newUrl = 'https://mcp.linear.app/v2/mcp';
+ const asOrigin = 'https://auth.example.com';
+ const realFetch = globalThis.fetch;
+ globalThis.fetch = (async (input, init) => {
+ const url = String(input);
+ if (url.includes('oauth-protected-resource')) {
+ return new Response(JSON.stringify({ resource: newUrl, authorization_servers: [asOrigin] }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ });
+ }
+ if (url.includes('oauth-authorization-server') || url.includes('openid-configuration')) {
+ return new Response(
+ JSON.stringify({
+ issuer: asOrigin,
+ authorization_endpoint: `${asOrigin}/authorize`,
+ token_endpoint: `${asOrigin}/token`,
+ registration_endpoint: `${asOrigin}/register`,
+ response_types_supported: ['code'],
+ code_challenge_methods_supported: ['S256'],
+ grant_types_supported: ['authorization_code', 'refresh_token'],
+ token_endpoint_auth_methods_supported: ['client_secret_post', 'none'],
+ }),
+ { status: 200, headers: { 'Content-Type': 'application/json' } },
+ );
+ }
+ if (url.includes('/register') && init?.method === 'POST') {
+ return new Response(
+ JSON.stringify({
+ client_id: 'new-url-client',
+ client_secret: 'new-url-secret',
+ token_endpoint_auth_method: 'client_secret_post',
+ // Absolute URLs only — SDK parses registration responses with SafeUrlSchema.
+ redirect_uris: [mcpOAuthCallbackUrl()],
+ grant_types: ['authorization_code', 'refresh_token'],
+ response_types: ['code'],
+ }),
+ { status: 200, headers: { 'Content-Type': 'application/json' } },
+ );
+ }
+ return new Response(`unexpected url: ${url}`, { status: 404 });
+ }) as typeof fetch;
+
+ try {
+ const response = await settingsRouter.request(
+ '/',
+ putInit({
+ ...putBodyWithDcr,
+ url: newUrl,
+ }),
+ );
+ expect(response.status).toBe(200);
+ // List/GET auth_status is presence-based; tokens are not cleared on re-DCR.
+ expect(await response.json()).toEqual({
+ data: {
+ ...putBodyWithDcr,
+ url: newUrl,
+ auth_status: { status: 'authenticated' },
+ },
+ });
+ expect(await tokenStore.getToken({ id: record.id, userRef: LOCAL_USER_CONTEXT.userRef })).toMatchObject({
+ accessToken: 'stale-for-old-url',
+ });
+ expect(await mcpServerStore.getClient({ id: record.id })).toMatchObject({
+ client: { clientId: 'new-url-client' },
+ });
+ } finally {
+ globalThis.fetch = realFetch;
+ // Restore baseline for later suite cases that still expect original linear URL / no token.
+ await mcpServerStore.upsertServer({
+ tenant_id: TENANT_ID,
+ name: putBodyWithDcr.name,
+ manifest: putBodyWithDcr,
+ });
+ await mcpServerStore.saveClient({
+ id: record.id,
+ record: {
+ server: {
+ authorizationEndpoint: 'https://auth.example.com/authorize',
+ tokenEndpoint: 'https://auth.example.com/token',
+ codeChallengeMethodsSupported: ['S256'],
+ },
+ client: {
+ clientId: 'seed-client',
+ clientSecret: 'seed-secret',
+ },
+ },
+ });
+ await tokenStore.deleteToken({ id: record.id, userRef: LOCAL_USER_CONTEXT.userRef });
+ }
+ });
+
it('PUT with header auth stores headers and reports authenticated', async () => {
const response = await settingsRouter.request('/', putInit(putBodyWithHeaderAuth));
expect(response.status).toBe(200);
@@ -362,13 +490,12 @@ describe('mcp-servers routers', () => {
auth: { type: 'dcr' },
}),
);
- expect(put.status).toBe(200);
+ // Registration fails before any DB write — no server exists to authorize.
+ expect(put.status).toBe(422);
+ expect(await mcpServerStore.getServer({ tenant_id: TENANT_ID, name: 'failing-oauth-mcp' })).toBeUndefined();
const authorize = await mcpServersRouter.request('/failing-oauth-mcp/authorize');
- expect(authorize.status).toBe(424);
- expect(await authorize.json()).toEqual({
- error: { message: "Failed to dynamically register OAuth client for MCP server 'failing-oauth-mcp'" },
- });
+ expect(authorize.status).toBe(404);
} finally {
globalThis.fetch = realFetch;
}
@@ -446,11 +573,7 @@ describe('mcp-servers routers', () => {
});
it('DELETE /{name}/authorize removes the DCR token, keeps the client, and reports auth_required', async () => {
- await settingsRouter.request('/', putInit(putBodyWithDcr));
- const record = await mcpServerStore.getServer({ tenant_id: TENANT_ID, name: putBodyWithDcr.name });
- if (!record) {
- throw new Error('expected DCR server to exist');
- }
+ const record = await seedDcrServerWithClient();
await mcpServerStore.saveClient({
id: record.id,
diff --git a/packages/server/tests/unit/runtime/getMcpConnection.test.ts b/packages/server/tests/unit/runtime/getMcpConnection.test.ts
index a90b28717..81bb02547 100644
--- a/packages/server/tests/unit/runtime/getMcpConnection.test.ts
+++ b/packages/server/tests/unit/runtime/getMcpConnection.test.ts
@@ -8,11 +8,12 @@ import { mcpOAuthCallbackUrl } from '../../../src/mcp/auth/mcpOAuthHelpers';
import { getMcpConnection } from '../../../src/runtime/sessionResources';
describe('getMcpConnection', () => {
+ let db: ReturnType<typeof createSqliteDb>;
let mcpServerStore: SqliteMcpServerStore;
let tokenStore: SqliteOAuthTokenStore;
beforeAll(async () => {
- const db = createSqliteDb(':memory:');
+ db = createSqliteDb(':memory:');
await migrateSqliteToLatest(db);
mcpServerStore = new SqliteMcpServerStore(db);
tokenStore = new SqliteOAuthTokenStore(db);