Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
6d85393
feat: x-tfg-mcp-headers to pass MCP credentials and skip consent, wit…
rutvij-menavlikar Nov 10, 2026
c09705e
Merge remote-tracking branch 'origin/main' into rutvij/age-2723_1
cursoragent Nov 12, 2026
b6007af
feat: use gateway 401 authorization_urls for MCP auth_required; drop …
cursoragent Nov 12, 2026
cf1d6c5
refactor: trim MCP auth changes and shorten comments (AGE-2723)
cursoragent Nov 12, 2026
a15ecff
chore: merge changesets into one (AGE-2723)
cursoragent Nov 12, 2026
e57439b
fix: accept only http(s) consent URLs from MCP 401 bodies (AGE-2723)
cursoragent Nov 12, 2026
014c4bc
feat: accept nested x-tfg-mcp-headers entries for virtual MCPs (AGE-2…
cursoragent Nov 12, 2026
0550d0e
chore: keep x-tfg-mcp-headers error message and shorten changeset (AG…
cursoragent Nov 12, 2026
8ca71f6
Merge branch 'main' into rutvij/age-2723_1
rutvij-menavlikar Nov 12, 2026
76eb522
feat: forward nested x-tfg-mcp-headers entries in open-source mode to…
cursoragent Nov 12, 2026
d16ae4a
Merge remote-tracking branch 'origin/rutvij/age-2723_1' into rutvij/a…
cursoragent Nov 12, 2026
d5efb54
chore: keep original doc wording for moved MCP header helpers (AGE-2723)
cursoragent Nov 12, 2026
0027e08
feat: send nested x-tfg-mcp-headers entries as plain headers in open-…
cursoragent Nov 12, 2026
11b1046
fix: reject managed MCP transport headers in x-tfg-mcp-headers (AGE-2…
cursoragent Nov 12, 2026
550abe6
Merge branch 'main' into rutvij/age-2723_1
rutvij-menavlikar Nov 12, 2026
59979c3
fix: keep onUnauthorized fallback when stamping session header (AGE-2…
rutvij-menavlikar Nov 13, 2026
64fd20f
fix: cap 401 SSE bodies and drop the rejected MCP session on consent …
cursoragent Nov 13, 2026
5f8755e
refactor: move per-server MCP headers out of src/mcp and keep TrueFou…
cursoragent Nov 16, 2026
408c61d
refactor: move TrueFoundry gateway 401 parsing into truefoundry/ (AGE…
cursoragent Nov 16, 2026
3aa59d9
Revert "refactor: move TrueFoundry gateway 401 parsing into truefound…
cursoragent Nov 16, 2026
f7199c7
Revert "refactor: move per-server MCP headers out of src/mcp and keep…
cursoragent Nov 16, 2026
a7c46dd
refactor: move per-server MCP headers to src/runtime and split TrueFo…
cursoragent Nov 16, 2026
39ed31a
refactor: accept virtual MCP header entries only in TrueFoundry mode …
cursoragent Nov 16, 2026
3206498
refactor: drop the onUnauthorized fallback; a 401 either carries cons…
cursoragent Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .changeset/x-tfg-mcp-headers-auth.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
'@truefoundry/trueforge-core': patch
'@truefoundry/trueforge': patch
---

`x-tfg-mcp-headers` entries with `Authorization` skip that MCP server's consent flow (forwarded directly in open-source mode, sent as `x-tfy-mcp-headers` in TrueFoundry mode). Nested virtual MCP entries are accepted only in TrueFoundry mode, where they are sent as `x-tfy-mcp-headers`. TrueFoundry mode no longer calls MCP authorize during turns. A 401 with `authorization_urls` pauses the turn with `mcp.auth_required`; any other 401 fails as an MCP error.
12 changes: 12 additions & 0 deletions packages/trueforge-core/src/core/errors.ts
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,18 @@ export class McpConnectionError extends AgentHarnessError {
}
}

/** A 401 whose body lists consent URLs (`authorization_urls`, keyed by server name). */
export class McpAuthorizationRequiredError extends McpConnectionError {
constructor(
message: string,
readonly authorizationUrls: Readonly<Record<string, string>>,
options?: ErrorOptions,
) {
super(message, 401, options);
this.name = 'McpAuthorizationRequiredError';
}
}

/**
* An MCP server's `auth.type: dcr` is unsatisfiable by configuration, not by a transient fault
*/
Expand Down
42 changes: 40 additions & 2 deletions packages/trueforge-core/src/core/mcp/RemoteMCP.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,12 @@
import type { CallToolRequest } from '@modelcontextprotocol/sdk/types.js';
import type { Logger } from 'winston';
import { applyErrorPrefix, MCP_ERROR_PREFIX, McpConnectionError, stripErrorPrefix } from '../errors';
import {
applyErrorPrefix,
MCP_ERROR_PREFIX,
McpAuthorizationRequiredError,
McpConnectionError,
stripErrorPrefix,
} from '../errors';
import type { MCPServerInitInfo } from '../events/schema';
import type { InternalToolCallInfo } from '../llm/LLMTypes';
import {
Expand Down Expand Up @@ -184,7 +190,39 @@ export class RemoteMCP implements ToolSource {
if ('authRequired' in headersResult) {
return { authRequired: headersResult.authRequired };
}
return this.connectAndRun(headersResult.headers, operation, true);
let used: RemoteMcpConnection | undefined;
const tracked = (connection: RemoteMcpConnection): Promise<T> => {
used = connection;
return operation(connection);
};
try {
return await this.connectAndRun(headersResult.headers, tracked, true);
} catch (error) {
const authRequired = this.authRequiredFrom(error);
if (authRequired === undefined) {
throw error;
}
// Reset only the rejected connection; a failed connect still leaves the old session and tools.
if (used !== undefined) {
await this.resetConnection(used);
} else if (!this.isConnected) {
this.sessionId = undefined;
this.cachedTools = undefined;
}
return { authRequired };
}
}

/** A 401 that carried consent URLs becomes authRequired; a bare 401 stays an error. */
private authRequiredFrom(error: unknown): MCPAuthRequired | undefined {
for (let current: unknown = error; current instanceof Error; current = current.cause) {
if (current instanceof McpAuthorizationRequiredError) {
const urls = current.authorizationUrls;
const authUrl = urls[this.name] ?? Object.values(urls)[0];
return authUrl === undefined ? undefined : { servers: [{ id: this.id, name: this.name, auth_url: authUrl }] };
}
}
return undefined;
}

private async connectAndRun<T>(
Expand Down
36 changes: 33 additions & 3 deletions packages/trueforge-core/src/core/mcp/remoteMcpClient.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@ import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/
import type { FetchLike } from '@modelcontextprotocol/sdk/shared/transport.js';
import type { CallToolRequest, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
import { context, propagation } from '@opentelemetry/api';
import { McpConnectionError } from '../errors';
import { z } from 'zod';
import { McpAuthorizationRequiredError, McpConnectionError } from '../errors';
import { elapsedSeconds, getOperationMetrics, type McpConnectOutcome } from '../observability/operationMetrics';
import { mcpSsrfFetch } from '../util/outboundFetch';
import { PromiseTimeoutError, withTimeout } from '../util/promiseUtils';
Expand Down Expand Up @@ -35,11 +36,12 @@ const TRANSPORT_PROBE_ORDER: RemoteMcpTransportType[] = ['streamable-http', 'sse

export const DEFAULT_MAX_MCP_RESPONSE_BYTES = 50 * 1024 * 1024;

/** GET SSE is long-lived and uncapped; every other body aborts at `maxBytes`. */
/** A successful GET SSE is long-lived and uncapped; every other body aborts at `maxBytes`. */
export function withMaxResponseBytes(fetchFn: FetchLike, maxBytes: number): FetchLike {
return async (url, init) => {
const response = await fetchFn(url, init);
const isGetSse =
response.ok &&
(init?.method ?? 'GET').toUpperCase() === 'GET' &&
(response.headers.get('content-type') ?? '').toLowerCase().includes('text/event-stream');
if (isGetSse || !response.body) {
Expand Down Expand Up @@ -69,6 +71,29 @@ export function withMaxResponseBytes(fetchFn: FetchLike, maxBytes: number): Fetc
};
}

const AuthorizationRequiredBodySchema = z.object({
authorization_urls: z.record(z.string(), z.url({ protocol: /^https?$/ })),

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why do we want to put regex on protocol?

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

z.url() accepts any scheme, including javascript:, data: and file:. These authorization_urls come from the upstream and are shown to the user as the consent link (auth_url). Restricting to http(s) stops a bad or compromised upstream from putting a script or local-file URL into that link. A body with any other scheme is treated as a bare 401.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simpler version: this URL comes from the server and is shown to the user as a link. Without the check, a bad server could send a javascript: or file: link. We only accept http and https.

});

/** A 401 whose body lists `authorization_urls` throws `McpAuthorizationRequiredError`; other responses pass through. */
export function withAuthorizationRequired(fetchFn: FetchLike): FetchLike {
return async (url, init) => {
const response = await fetchFn(url, init);
if (response.status !== 401) {
return response;
}
const body: unknown = await response
.clone()
.json()
.catch(() => undefined);
const parsed = AuthorizationRequiredBodySchema.safeParse(body);
if (!parsed.success || Object.keys(parsed.data.authorization_urls).length === 0) {
return response;
}
throw new McpAuthorizationRequiredError('upstream requires authorization', parsed.data.authorization_urls);
};
}

class McpClientWithTimeout extends Client {
constructor(private readonly requestTimeoutMs: number) {
super(CLIENT_INFO, { capabilities: {} });
Expand Down Expand Up @@ -128,6 +153,9 @@ function isAuthError(error: unknown): boolean {
if (!(error instanceof Error)) {
return false;
}
if (error instanceof McpConnectionError) {
return error.statusCode === 401;
}
Comment on lines +156 to +158

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

since McpAuthorizationRequiredError extends McpConnectionError will this create problems?

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's intentional. As a 401 McpConnectionError it stops the connect probe without trying other transports, keeps its subclass through toConnectError, is counted as an auth outcome in metrics, and looks like an ordinary 401 to code that doesn't know the subclass. The one place that must tell it apart is the onUnauthorized fallback in RemoteMCP.executeWithAuthFallback. That code checks authRequiredFrom(error) before falling back, so a 401 carrying consent URLs becomes authRequired instead of retrying with fallback credentials.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simpler version: no, it's on purpose. It is still a 401, so everything that handles 401s keeps working (we stop trying other transports, metrics count it as auth, callers see a 401). Only RemoteMCP checks for the subclass, to turn it into mcp.auth_required with the consent URL.

if ('code' in error && error.code === 401) {
return true;
}
Expand Down Expand Up @@ -212,7 +240,9 @@ export async function connectRemoteMcp(params: {
const customFetch = params.fetch;
const transportFetch: RemoteMcpFetch =
customFetch === undefined ? mcpSsrfFetch : (input, init) => customFetch(input, { ...init, redirect: 'manual' });
const fetchFn = withMaxResponseBytes(transportFetch, params.maxResponseBytes ?? DEFAULT_MAX_MCP_RESPONSE_BYTES);
const fetchFn = withAuthorizationRequired(
withMaxResponseBytes(transportFetch, params.maxResponseBytes ?? DEFAULT_MAX_MCP_RESPONSE_BYTES),
);
const candidates = params.knownTransportType
? [params.knownTransportType, ...TRANSPORT_PROBE_ORDER.filter(t => t !== params.knownTransportType)]
: TRANSPORT_PROBE_ORDER;
Expand Down
28 changes: 28 additions & 0 deletions packages/trueforge-core/tests/core/mcp/connectRemoteMcp.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,34 @@ describe('connectRemoteMcp custom fetch', () => {

expect(fetch).toHaveBeenCalledWith(endpoint, expect.objectContaining({ redirect: 'manual' }));
});

it('turns a 401 with authorization_urls into McpAuthorizationRequiredError and passes a bare 401 through', async () => {
const urls = { github: 'https://auth.example/consent' };
const fetch = jest
.fn<Promise<Response>, Parameters<RemoteMcpFetch>>()
.mockResolvedValueOnce(
new Response(JSON.stringify({ error: { type: 'McpAuthRequiredError' }, authorization_urls: urls }), {
status: 401,
}),
)
.mockResolvedValueOnce(new Response('unauthorized', { status: 401 }))
.mockResolvedValueOnce(
new Response(JSON.stringify({ authorization_urls: { github: 'javascript:alert(1)' } }), { status: 401 }),
);
await connectRemoteMcp({ ...baseParams(), url: endpoint, knownTransportType: 'streamable-http', fetch });
const transportFetch = mockTransportFetches[0];
if (transportFetch === undefined) {
throw new Error('expected transport fetch');
}

await expect(transportFetch(endpoint, {})).rejects.toMatchObject({
name: 'McpAuthorizationRequiredError',
statusCode: 401,
authorizationUrls: urls,
});
await expect(transportFetch(endpoint, {})).resolves.toMatchObject({ status: 401 });
await expect(transportFetch(endpoint, {})).resolves.toMatchObject({ status: 401 });
});
});

describe('connectRemoteMcp transport selection', () => {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -33,4 +33,15 @@ describe('withMaxResponseBytes', () => {

expect((await response.arrayBuffer()).byteLength).toBe(80);
});

it('caps a non-OK GET text/event-stream body', async () => {
const fetchFn = withMaxResponseBytes(
async () =>
new Response(streamOf(new Uint8Array(80)), { status: 401, headers: { 'content-type': 'text/event-stream' } }),
50,
);
const response = await fetchFn('https://mcp.example.com', { method: 'GET' });

await expect(response.arrayBuffer()).rejects.toThrow(/exceeded max 50 bytes/);
});
});
33 changes: 33 additions & 0 deletions packages/trueforge-core/tests/core/mcp/remoteMcpServer.test.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import type { Logger } from 'winston';
import { McpConnectionError, RemoteMCP, ToolSet } from '../../../src/core';
import { McpAuthorizationRequiredError } from '../../../src/core/errors';
import {
isApprovalRequiredResponse,
isCallToolResponseResult,
Expand Down Expand Up @@ -473,6 +474,38 @@ describe('RemoteMCP + ToolSet', () => {
expect(state.callToolCalls).toBe(0);
});

it('returns authRequired from a 401 that carries authorization URLs', async () => {
installFakeConnection({
connectError: new McpAuthorizationRequiredError('auth required', { 'my-inline': 'https://auth.example/consent' }),
});
const server = makeServer({ headers: () => Promise.resolve({ headers: {} }) });

await expect(server.listTools()).resolves.toEqual({
authRequired: { servers: [{ id: 'inline-id-123', name: 'my-inline', auth_url: 'https://auth.example/consent' }] },
});
});

it('drops the rejected connection when a call returns consent URLs, so the next call reconnects', async () => {
const state = installFakeConnection({ sessionId: 'sess-1' });
const server = makeServer({ headers: () => Promise.resolve({ headers: {} }) });

await server.listTools();
state.queueCallToolError(
new McpAuthorizationRequiredError('auth required', { 'my-inline': 'https://auth.example/consent' }),
);
await expect(server.callTool({ name: 'read_thing', arguments: {} })).resolves.toHaveProperty('authRequired');
await server.callTool({ name: 'read_thing', arguments: {} });

expect(state.connectCalls).toBe(2);
});

it('throws on a bare 401', async () => {
installFakeConnection({ connectError: new McpConnectionError('upstream 401', 401) });
const server = makeServer({ headers: () => Promise.resolve({ headers: {} }) });

await expect(server.listTools()).rejects.toMatchObject({ statusCode: 401 });
});

it('emits init for a stateless (SSE) server on connect (matches gateway strict-compare behavior)', async () => {
// Stateless connection reports a null session id.
installFakeConnection({ sessionId: null });
Expand Down
2 changes: 1 addition & 1 deletion packages/trueforge/src/apis/turns.ts
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,7 @@ import {
type EventSubscriptionPollOptions,
type EventSubscriptionRegistry,
} from '../runtime/event-subscription';
import { X_TFG_MCP_HEADERS } from '../runtime/perServerMcpHeaders';
import { validateSandboxFilePath } from '../runtime/sandboxFilePath';
import {
buildTurnSandbox,
Expand All @@ -122,7 +123,6 @@ import { restoreTurnEventLog } from '../runtime/turnEventLogRestore';
import { MAX_SESSION_TITLE_LENGTH } from '../schemas/session';
import { assertGatewayMetadataRequestHeaders, X_TFY_METADATA } from '../truefoundry/gatewayMetadata';
import { X_TFG_MCP, X_TFG_MODELS, X_TFG_SKILLS, X_TFG_TOOLS } from '../truefoundry/inlineResources';
import { X_TFG_MCP_HEADERS } from '../truefoundry/perServerMcpHeaders';
import { newId } from '../utils/id';
import { resolveWebSearchProvider } from '../websearch/providers';
import { canReadAgentBoundResource, canReadSession } from './agentAccess';
Expand Down
12 changes: 12 additions & 0 deletions packages/trueforge/src/db/McpServerWithAuthStore.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import type { RemoteMcpHeaders } from '@truefoundry/trueforge-core/core';
import { isMcpAuthRequired, resolveMcpAuth } from '../mcp/auth/mcpDcr';
import type { IOAuthTokenStore, OAuthClientRecord } from '../mcp/auth/types';
import { withCallerMcpHeaders, type PerServerMcpHeaders } from '../runtime/perServerMcpHeaders';
import { resolveConfiguredMcpRequestHeaders, resolveMcpAuthStatus, type McpAuthStatus } from '../schemas/mcpServer';
import {
McpServerNotFoundError,
Expand All @@ -22,15 +23,18 @@ export class McpServerWithAuthStore<TTransaction = never> implements IMcpServerW
readonly #store: IMcpServerStore<TTransaction>;
readonly #tokenStore: IOAuthTokenStore<TTransaction>;
readonly #clientName: string;
readonly #perServerHeaders: PerServerMcpHeaders;

constructor(input: {
store: IMcpServerStore<TTransaction>;
tokenStore: IOAuthTokenStore<TTransaction>;
clientName: string;
perServerHeaders?: PerServerMcpHeaders;
}) {
this.#store = input.store;
this.#tokenStore = input.tokenStore;
this.#clientName = input.clientName;
this.#perServerHeaders = input.perServerHeaders ?? {};
}

listServers(input: ListMcpServersInput, transaction?: TTransaction): Promise<McpServerRecord[]> {
Expand Down Expand Up @@ -62,6 +66,14 @@ export class McpServerWithAuthStore<TTransaction = never> implements IMcpServerW
userRef: string;
turnMetadata?: TurnMetadata;
}): RemoteMcpHeaders {
return withCallerMcpHeaders({
callerHeaders: this.#perServerHeaders[input.record.name],
registeredHeaders: this.#resolveRegisteredHeaders(input),
configuredHeaders: resolveConfiguredMcpRequestHeaders(input.record.manifest),
});
}

#resolveRegisteredHeaders(input: { record: McpServerRecord; userRef: string }): RemoteMcpHeaders {
const { record, userRef } = input;
if (record.manifest.auth?.type === 'dcr') {
return async () => {
Expand Down
10 changes: 8 additions & 2 deletions packages/trueforge/src/main.ts
Original file line number Diff line number Diff line change
Expand Up @@ -319,8 +319,9 @@ async function createStandalonePersistence(options: {
const tokenStore = new SqliteOAuthTokenStore(db);
const agentStore = new SqliteAgentStore(db);
const modelProviderStore = new SqliteModelProviderStore(db);
const mcpPersistenceStore = new SqliteMcpServerStore(db);
const mcpServerStore = new McpServerWithAuthStore({
store: new SqliteMcpServerStore(db),
store: mcpPersistenceStore,
tokenStore,
clientName: configuration.MCP_DCR_OAUTH_CLIENT_NAME,
});
Expand All @@ -345,7 +346,12 @@ async function createStandalonePersistence(options: {
mcpOAuthStore: mcpServerStore,
redis: undefined,
resolveAgentStore: () => agentStore,
resolveMcpServerStore: () => mcpServerStore,
resolveMcpServerStore: buildResolveMcpServerStore({
persistenceStore: mcpPersistenceStore,
tokenStore,
client: undefined,
logger,
}),
resolveModelProviderStore: () => modelProviderStore,
resolveSkillStore: () => skillStore,
resolveTurnSkillsStore: buildResolveTurnSkillsStore({
Expand Down
Loading
Loading