Skip to content
Open
Show file tree
Hide file tree
Changes from 22 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 sent as JSON-valued headers in open-source mode and as `x-tfy-mcp-headers` in TrueFoundry mode), falling back to the server's regular auth on a 401. TrueFoundry mode no longer calls MCP authorize during turns: a 401 with `authorization_urls` pauses the turn with `mcp.auth_required`, and a bare 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
104 changes: 100 additions & 4 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 All @@ -24,6 +30,7 @@ import { paginateWithCursorGuard } from './pagination';
import {
connectRemoteMcp,
DEFAULT_MAX_MCP_RESPONSE_BYTES,
isAuthError,
isSessionExpiredError,
type RemoteMcpConnection,
type RemoteMcpFetch,
Expand All @@ -40,8 +47,13 @@ function redactUrlForTrace(url: string): string {
}
}

/** What a headers resolver returns: the headers to send, or a signal that auth is required. */
export type ResolveHeadersResult = { headers: Record<string, string> } | { authRequired: MCPAuthRequired };
/**
* What a headers resolver returns: the headers to send, or a signal that auth is required.
* `onUnauthorized` is consulted once if the upstream rejects `headers` with a 401.
*/
export type ResolveHeadersResult =
| { headers: Record<string, string>; onUnauthorized?: () => Promise<ResolveHeadersResult> }
| { authRequired: MCPAuthRequired };

/** Static headers, or a resolver (invoked at connect) returning headers or signalling auth-required. */
export type RemoteMcpHeaders = Record<string, string> | (() => Promise<ResolveHeadersResult>);
Expand Down Expand Up @@ -87,6 +99,8 @@ export class RemoteMCP implements ToolSource {
private cachedTools?: AgentToolSchema[] | undefined;
private inflight = 0;
private pendingClose: RemoteMcpConnection | undefined;
// Connection opened with onUnauthorized fallback headers; its auth is re-checked before reuse.
private fallbackConnection: RemoteMcpConnection | undefined;

constructor(params: {
id: string;
Expand Down Expand Up @@ -176,6 +190,48 @@ export class RemoteMCP implements ToolSource {

private async executeWithSessionRetry<T>(
operation: (connection: RemoteMcpConnection) => Promise<T>,
): Promise<ExecuteResult<T>> {
let used: RemoteMcpConnection | undefined;
const tracked = (connection: RemoteMcpConnection): Promise<T> => {
used = connection;
return operation(connection);
};
try {
return await this.executeWithAuthFallback(tracked);
} catch (error) {
const authRequired = this.authRequiredFrom(error);
if (authRequired === undefined) {
throw error;
}
await this.discardRejected(used);
return { authRequired };
}
Comment thread
cursor[bot] marked this conversation as resolved.
Resolved
}

// Reset only the rejected connection; a failed connect still leaves the old session and tools.
private async discardRejected(rejected: RemoteMcpConnection | undefined): Promise<void> {
if (rejected !== undefined) {
await this.resetConnection(rejected);
} else if (!this.isConnected) {
this.sessionId = undefined;
this.cachedTools = undefined;
}
}

/** 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 executeWithAuthFallback<T>(
operation: (connection: RemoteMcpConnection) => Promise<T>,
): Promise<ExecuteResult<T>> {
// Auth is re-checked on every operation, not only on the first connect: a registered server's OAuth
// can be revoked or expire mid-request, and callers must get authRequired rather than a generic
Expand All @@ -184,7 +240,47 @@ export class RemoteMCP implements ToolSource {
if ('authRequired' in headersResult) {
return { authRequired: headersResult.authRequired };
}
return this.connectAndRun(headersResult.headers, operation, true);
const { onUnauthorized } = headersResult;
if (onUnauthorized === undefined) {
return this.connectAndRun(headersResult.headers, operation, true);
}
if (this.isConnected && this._connection !== undefined && this._connection === this.fallbackConnection) {
// Re-check the fallback auth before reusing its connection so a disconnected account stops here.
return this.runWithFallback(onUnauthorized, operation);
}
let rejected: RemoteMcpConnection | undefined;
const tracked = (connection: RemoteMcpConnection): Promise<T> => {
rejected = connection;
return operation(connection);
};
try {
return await this.connectAndRun(headersResult.headers, tracked, true);
} catch (error) {
if (!isAuthError(error) || this.authRequiredFrom(error) !== undefined) {
throw error;
}
this.logger.info(`Remote MCP ${this.name} rejected supplied credentials, falling back to its auth flow`);
await this.discardRejected(rejected);
return this.runWithFallback(onUnauthorized, operation);
}
}

private async runWithFallback<T>(
onUnauthorized: () => Promise<ResolveHeadersResult>,
operation: (connection: RemoteMcpConnection) => Promise<T>,
): Promise<ExecuteResult<T>> {
const fallback = await onUnauthorized();
if ('authRequired' in fallback) {
if (this.fallbackConnection !== undefined) {
await this.resetConnection(this.fallbackConnection);
}
return { authRequired: fallback.authRequired };
}
const tracked = (connection: RemoteMcpConnection): Promise<T> => {
this.fallbackConnection = connection;
return operation(connection);
};
return this.connectAndRun(fallback.headers, tracked, true);
Comment thread
cursor[bot] marked this conversation as resolved.
Resolved
}

private async connectAndRun<T>(
Expand Down
39 changes: 35 additions & 4 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()
Comment thread
cursor[bot] marked this conversation as resolved.
Resolved
.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 @@ -124,10 +149,14 @@ function mcpConnectOutcome(error: unknown): McpConnectOutcome {
return 'other';
}

function isAuthError(error: unknown): boolean {
/** Upstream rejected the credentials, whether at connect or on a later request. */
export 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 +241,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/);
});
});
Loading
Loading