Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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` passes per-MCP-server headers. Open-source mode merges a server's entry over its registered headers, and an entry `Authorization` skips DCR. TrueFoundry mode sends the entry (flat, or a nested virtual MCP map) as `x-tfy-mcp-headers` and no longer calls authorize before connecting. On a 401: open-source fails when the entry carried `Authorization`, otherwise a DCR server restarts consent; TrueFoundry fails whenever the server had an entry, otherwise asks authorize for a consent URL and fails with 422 when authorize returns none or reports no consent is needed.
45 changes: 42 additions & 3 deletions packages/trueforge-core/src/core/mcp/RemoteMCP.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ import { paginateWithCursorGuard } from './pagination';
import {
connectRemoteMcp,
DEFAULT_MAX_MCP_RESPONSE_BYTES,
isAuthError,
isSessionExpiredError,
type RemoteMcpConnection,
type RemoteMcpTransportType,
Expand All @@ -33,8 +34,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.
* On a 401, `onUnauthorized` may offer a way to start authorization consent. Without the hook, the 401 fails.
*/
export type ResolveHeadersResult =
| { headers: Record<string, string>; onUnauthorized?: () => Promise<MCPAuthRequired> }
| { 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 @@ -170,7 +176,40 @@ 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) {
let authRequired: MCPAuthRequired | undefined = undefined;
try {
if (isAuthError(error)) {
// Start consent on a 401 if the headers resolver offers a hook.
authRequired = await headersResult.onUnauthorized?.();
}
} catch (recoveryError) {
// Rethrow the recovery error unchanged so its status survives, with the 401 it replaced as
// `cause` — error logging already walks that chain.
if (recoveryError instanceof Error && recoveryError.cause === undefined) {
recoveryError.cause = error;
}
throw recoveryError;
}
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 };
}
}

private async connectAndRun<T>(
Expand Down
5 changes: 4 additions & 1 deletion packages/trueforge-core/src/core/mcp/remoteMcpClient.ts
Original file line number Diff line number Diff line change
Expand Up @@ -104,10 +104,13 @@ export function isSessionExpiredError(error: unknown): boolean {
return error.message.includes('HTTP 404') || error.message.toLowerCase().includes('session');
}

function isAuthError(error: unknown): boolean {
export function isAuthError(error: unknown): boolean {
if (!(error instanceof Error)) {
return false;
}
if (error instanceof McpConnectionError) {
return error.statusCode === 401;
}
if ('code' in error && error.code === 401) {
return true;
}
Expand Down
50 changes: 50 additions & 0 deletions packages/trueforge-core/tests/core/mcp/remoteMcpServer.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -429,6 +429,56 @@ describe('RemoteMCP + ToolSet', () => {
expect(state.callToolCalls).toBe(0);
});

it('returns authRequired when the resolver offers consent for a 401', async () => {
installFakeConnection({ connectError: new McpConnectionError('upstream 401', 401) });
const authRequired: MCPAuthRequired = {
servers: [{ id: 'inline-id-123', name: 'my-inline', auth_url: 'https://auth.example/consent' }],
};
const server = makeServer({
headers: () => Promise.resolve({ headers: {}, onUnauthorized: () => Promise.resolve(authRequired) }),
});

await expect(server.listTools()).resolves.toEqual({ authRequired });
});

it('drops the rejected connection when a call gets a 401 with consent, so the next call reconnects', async () => {
const state = installFakeConnection({ sessionId: 'sess-1' });
const authRequired: MCPAuthRequired = {
servers: [{ id: 'inline-id-123', name: 'my-inline', auth_url: 'https://auth.example/consent' }],
};
const server = makeServer({
headers: () => Promise.resolve({ headers: {}, onUnauthorized: () => Promise.resolve(authRequired) }),
});

await server.listTools();
state.queueCallToolError(Object.assign(new Error('HTTP 401'), { code: 401 }));
await expect(server.callTool({ name: 'read_thing', arguments: {} })).resolves.toEqual({ authRequired });
await server.callTool({ name: 'read_thing', arguments: {} });

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

it('throws the 401 when the resolver offers no consent', async () => {
installFakeConnection({ connectError: new McpConnectionError('upstream 401', 401) });
const server = makeServer({
headers: () => Promise.resolve({ headers: {} }),
});

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

it('propagates the resolver error when the consent lookup fails', async () => {
installFakeConnection({ connectError: new McpConnectionError('upstream 401', 401) });
const server = makeServer({
headers: () => Promise.resolve({ headers: {}, onUnauthorized: () => Promise.reject(new Error('lookup failed')) }),
});

await expect(server.listTools()).rejects.toMatchObject({
message: 'lookup failed',
cause: expect.objectContaining({ 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
58 changes: 54 additions & 4 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 { RemoteMcpHeaders, ResolveHeadersResult } from '@truefoundry/trueforge-core/core';
import { beginMcpAuthorization, isMcpAuthRequired, resolveMcpAuth } from '../mcp/auth/mcpDcr';
import type { IOAuthTokenStore, OAuthClientRecord } from '../mcp/auth/types';
import { hasAuthorizationHeader, mergeServerHeaders, 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,9 +66,40 @@ export class McpServerWithAuthStore<TTransaction = never> implements IMcpServerW
userRef: string;
turnMetadata?: TurnMetadata;
}): RemoteMcpHeaders {
const { record } = input;
const overrideServerHeaders = this.#perServerHeaders[record.name];
// Authorization in x-tfg-mcp-headers is the credential sent to the MCP. Skip the DCR token, and
// attach no 401 hook, so a rejection fails instead of starting consent.
if (overrideServerHeaders !== undefined && hasAuthorizationHeader(overrideServerHeaders)) {
const configuredHeaders = resolveConfiguredMcpRequestHeaders(record.manifest);
return mergeServerHeaders({ base: configuredHeaders, override: overrideServerHeaders });
}
const resolveHeaders = this.#buildResolveHeaders(input);
if (overrideServerHeaders === undefined) {
return resolveHeaders;
}
return async () => {
let resolvedHeaders: ResolveHeadersResult;
if (typeof resolveHeaders === 'function') {
resolvedHeaders = await resolveHeaders();
} else {
resolvedHeaders = { headers: resolveHeaders };
}
if ('authRequired' in resolvedHeaders) {
return resolvedHeaders;
}
return {
...resolvedHeaders,
headers: mergeServerHeaders({ base: resolvedHeaders.headers, override: overrideServerHeaders }),
};
};
}

/** DCR token (or consent before connect), otherwise the static manifest headers. No 401 hook unless DCR. */
#buildResolveHeaders(input: { record: McpServerRecord; userRef: string }): RemoteMcpHeaders {
const { record, userRef } = input;
if (record.manifest.auth?.type === 'dcr') {
return async () => {
return async (): Promise<ResolveHeadersResult> => {
const result = await resolveMcpAuth({
tokenStore: this.#tokenStore,
mcpServerStore: this.#store,
Expand All @@ -82,7 +117,22 @@ export class McpServerWithAuthStore<TTransaction = never> implements IMcpServerW
},
};
}
return { headers: result.headers };
return {
headers: result.headers,
// On a 401, start DCR consent; the stored token stays until the callback replaces it.
onUnauthorized: async () => {
const authorizationUrl = await beginMcpAuthorization({
tokenStore: this.#tokenStore,
mcpServerStore: this.#store,
serverId: record.id,
userRef,
mcpServerUrl: record.manifest.url,
mcpServerName: record.name,
clientName: this.#clientName,
});
return { servers: [{ id: record.name, name: record.name, auth_url: authorizationUrl.href }] };
},
};
};
}
return resolveConfiguredMcpRequestHeaders(record.manifest);
Expand Down
44 changes: 27 additions & 17 deletions packages/trueforge/src/main.ts
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,7 @@ import type { IOAuthTokenStore } from './mcp/auth/types';
import { PACKAGE_VERSION } from './packageVersion';
import { ActiveTurnRegistry } from './runtime/activeTurns';
import { EventSubscriptionRegistry } from './runtime/event-subscription';
import { parsePerServerMcpHeaders, X_TFG_MCP_HEADERS } from './runtime/perServerMcpHeaders';
import type { ConnectedRedis } from './runtime/redis';
import { initSentry } from './sentry';
import { printStandaloneStartupBanner } from './startupBanner';
Expand All @@ -134,11 +135,7 @@ import {
X_TFG_SKILLS,
} from './truefoundry/inlineResources';
import { InlineSkillStore } from './truefoundry/InlineSkillStore';
import {
parsePerServerMcpHeaders,
X_TFG_MCP_HEADERS,
type PerServerMcpHeaders,
} from './truefoundry/perServerMcpHeaders';
import { parseTrueFoundryPerServerMcpHeaders } from './truefoundry/perServerMcpHeaders';
import { TrueFoundryAgentStore } from './truefoundry/TrueFoundryAgentStore';
import { TrueFoundryAuthorizer } from './truefoundry/TrueFoundryAuthorizer';
import { TrueFoundryMcpServerStore } from './truefoundry/TrueFoundryMcpServerStore';
Expand All @@ -161,7 +158,7 @@ interface ServerPersistence<TTransaction> {
resolveMcpServerStore: (
rc: RequestContext,
runAsAgent?: AgentRecord,
perServerHeaders?: PerServerMcpHeaders,
rawPerServerHeaders?: string,
) => IMcpServerWithAuthStore<TTransaction>;
resolveSandboxProviderStore: (rc: RequestContext) => ISandboxProviderStore<TTransaction>;
resolveWebSearchProviderStore: (rc: RequestContext) => IWebSearchProviderStore<TTransaction>;
Expand Down Expand Up @@ -253,7 +250,8 @@ function buildResolveModelProviderStore<TTransaction>(options: {
}

/**
* Per-request MCP store over ServiceFoundry. `runAsAgent` selects a saved agent's token for turns.
* Per-request MCP store over ServiceFoundry, else the DB store with any `x-tfg-mcp-headers`.
* `runAsAgent` selects a saved agent's token for turns.
*/
function buildResolveMcpServerStore<TTransaction>(options: {
persistenceStore: IMcpServerStore<TTransaction>;
Expand All @@ -263,22 +261,32 @@ function buildResolveMcpServerStore<TTransaction>(options: {
}): (
rc: RequestContext,
runAsAgent?: AgentRecord,
perServerHeaders?: PerServerMcpHeaders,
rawPerServerHeaders?: string,
) => IMcpServerWithAuthStore<TTransaction> {
const withAuthMcpPersistenceStore = new McpServerWithAuthStore<TTransaction>({
store: options.persistenceStore,
tokenStore: options.tokenStore,
clientName: configuration.MCP_DCR_OAUTH_CLIENT_NAME,
});
return (rc, runAsAgent, perServerHeaders) => {
return (rc, runAsAgent, rawPerServerHeaders) => {
const { client } = options;
if (client) {
return new TrueFoundryMcpServerStore<TTransaction>({
client,
requestContext: rc,
agent: runAsAgent,
logger: options.logger,
...(perServerHeaders === undefined ? {} : { perServerHeaders }),
...(rawPerServerHeaders === undefined
? {}
: { perServerHeaders: parseTrueFoundryPerServerMcpHeaders(rawPerServerHeaders) }),
});
}
if (rawPerServerHeaders !== undefined) {
return new McpServerWithAuthStore<TTransaction>({
store: options.persistenceStore,
tokenStore: options.tokenStore,
clientName: configuration.MCP_DCR_OAUTH_CLIENT_NAME,
perServerHeaders: parsePerServerMcpHeaders(rawPerServerHeaders),
});
}
return withAuthMcpPersistenceStore;
Expand Down Expand Up @@ -388,8 +396,9 @@ async function createStandalonePersistence(options: {
const agentStore = new SqliteAgentStore(db);
const sandboxEnvironmentStore = wrapSandboxEnvironmentStore(new SqliteSandboxEnvironmentStore(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 @@ -404,7 +413,12 @@ async function createStandalonePersistence(options: {
tokenStore,
scheduleStore: new SqliteScheduleStore(db),
resolveModelProviderStore: () => modelProviderStore,
resolveMcpServerStore: () => mcpServerStore,
resolveMcpServerStore: buildResolveMcpServerStore({
persistenceStore: mcpPersistenceStore,
tokenStore,
client: undefined,
logger,
}),
resolveSandboxProviderStore: () => sandboxProviderStore,
resolveWebSearchProviderStore: () => webSearchProviderStore,
resolveSkillStore: () => skillStore,
Expand Down Expand Up @@ -650,11 +664,7 @@ async function createServerRuntime<TTransaction>(persistence: ServerPersistence<
return mcpOAuthStore;
}
const rawPerServerHeaders = c.req.header(X_TFG_MCP_HEADERS);
const store = persistence.resolveMcpServerStore(
resolveRequestContext(c),
runAsAgent,
rawPerServerHeaders === undefined ? undefined : parsePerServerMcpHeaders(rawPerServerHeaders),
);
const store = persistence.resolveMcpServerStore(resolveRequestContext(c), runAsAgent, rawPerServerHeaders);
if (!isTrueFoundryModeEnabled(configuration)) {
return store;
}
Expand Down
Loading
Loading