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.tsindex 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, McpServerReimport { 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: SettingsMcpSeconst 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.tsindex 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.tsindex 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.tsindex 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);