Skip to content

[AGE-2723] x-tfg-mcp-headers: pass MCP credentials and skip consent - #1313

Open
rutvij-menavlikar wants to merge 24 commits into
mainfrom
rutvij/age-2723_1
Open

rutvij-menavlikar wants to merge 24 commits into
mainfrom
rutvij/age-2723_1

Conversation

@rutvij-menavlikar

@rutvij-menavlikar rutvij-menavlikar commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Implements AGE-2723: x-tfg-mcp-headers support to pass tokens and skip auth on MCP servers.

x-tfg-mcp-headers: {"mcp-server-1": {"Authorization": "Bearer ..."}, "mcp-server-2": {...}}

A server whose entry has a top-level Authorization (any casing) skips its consent check (TrueFoundry authorize or open-source DCR) and uses the caller's credential instead. If the server rejects that credential with a 401, TrueForge falls back to the server's regular auth flow. This mirrors the TrueFoundry gateway's x-tfy-mcp-headers handling, where an authorization header skips token resolution.

Changes

  • Open-source mode: each server's entry is forwarded straight to that server, replacing registered headers of the same name (any casing). With Authorization, DCR consent is skipped; without it, the entry is layered on top of the server's normal auth. Standalone (sqlite) mode now uses the same resolver.
  • TrueFoundry mode: with Authorization, /authorize is skipped and the entry is sent as a flat x-tfy-mcp-headers on that server's gateway proxy connection (the gateway rejects a nested map there). The gateway Bearer stays the caller's. Entries without Authorization keep today's behavior.
  • 401 fallback: ResolveHeadersResult gains an optional onUnauthorized. On a 401 at connect or mid-session, RemoteMCP clears the rejected connection/session and retries once with the fallback headers, or returns authRequired so the turn pauses with the consent URL. Fallback is authorize in TrueFoundry mode and DCR or configured headers in open-source mode; the caller's non-Authorization headers are kept.
  • perServerMcpHeaders moved from truefoundry/ to mcp/ since both modes use it.
  • Inline (x-tfg-mcp) servers and virtual MCPs are unchanged.

How was this tested?

  • Per-server header tests (TrueFoundry mapping and skipped authorize, open-source forwarding and skipped DCR) and two core RemoteMCP tests (401 at connect, 401 mid-session).
  • Typecheck for core and trueforge, core tests/core/mcp, trueforge tests/unit/mcp and tests/unit/truefoundry, eslint and prettier on changed files.

Checklist

  • I have read the contributing guidelines
  • pnpm typecheck / tests / eslint / pnpm format:check pass locally for the touched packages
  • Tests added/updated where it makes sense
  • No hand-edits to generated code
  • Docs / .env.example updated if configuration or behavior changed (no config changes)

Note

High Risk
Changes authentication and identity forwarding for every MCP connection in both OSS and TrueFoundry modes; incorrect header merge or consent bypass could expose wrong credentials or skip required consent.

Reviewed by Cursor Bugbot for commit 3206498. Bugbot is set up for automated code reviews on this repo. Configure here.

Summary

Implements AGE-2723: x-tfg-mcp-headers support to pass tokens and skip auth on MCP servers.

x-tfg-mcp-headers: {"mcp-server-1": {"Authorization": "Bearer ..."}, "mcp-server-2": {...}}
x-tfg-mcp-headers: {"virtual-mcp": {"serv1": {...}, "serv2": {...}}}   # TrueFoundry mode only

A server whose entry has a top-level Authorization (any casing) skips its consent check and uses the caller's credential instead. This mirrors the TrueFoundry gateway's x-tfy-mcp-headers handling, where an authorization header skips token resolution. On a 401, a body with consent URLs starts the consent flow; any other 401 fails as an MCP error, whether or not a stored token exists.

Changes

  • Open-source mode: each server's entry is forwarded straight to that server, replacing registered headers of the same name (any casing). With Authorization, DCR consent is skipped; without it, the entry is layered on top of the server's normal auth. Nested entries are rejected with 400. Standalone (sqlite) mode now uses the same resolver.
  • TrueFoundry mode: turns no longer call /authorize; connections use the gateway Bearer plus turn metadata. An entry with Authorization, or a virtual MCP's nested entry, is sent as x-tfy-mcp-headers on that server's gateway proxy connection. Other entries keep today's merge. authorize stays for the explicit Connect flow.
  • 401 handling (core): a 401 whose body has http(s) authorization_urls returns authRequired (turn pauses with mcp.auth_required) and drops the rejected connection; a bare 401 throws McpConnectionError.
  • x-tfg-mcp-headers now rejects mcp-session-id / mcp-protocol-version, which TrueForge manages.
  • perServerMcpHeaders moved from truefoundry/ to runtime/ since both modes use it; the TrueFoundry-only nested schema lives in truefoundry/virtualMcpHeaders.ts.
  • Inline (x-tfg-mcp) servers are unchanged.

How was this tested?

  • Per-server header tests (open-source forwarding and skipped DCR, nested entries rejected; TrueFoundry x-tfy-mcp-headers mapping, nested pass-through, no authorize call) and core RemoteMCP tests (401 with consent URLs, reconnect after consent, bare 401).
  • Typecheck for core and trueforge, core tests/core, trueforge tests/unit, eslint and prettier on changed files.

Checklist

  • I have read the contributing guidelines
  • pnpm typecheck / tests / eslint / pnpm format:check pass locally for the touched packages
  • Tests added/updated where it makes sense
  • No hand-edits to generated code
  • Docs / .env.example updated if configuration or behavior changed (no config changes)
Open in Web Open in Cursor 

@changeset-bot

changeset-bot Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 3206498

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages
Name Type
@truefoundry/trueforge-core Patch
@truefoundry/trueforge Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@veria-ai

veria-ai Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

PR overview

All previously flagged issues have been addressed. No open security concerns remain on this pull request.

Fixed/addressed: 5 · PR risk: 0/10

Reviews

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Stale Bugbot comment from a previous run.

@rutvij-menavlikar rutvij-menavlikar changed the title [AGE-2723] core: RemoteMCP onUnauthorized fallback for rejected MCP credentials [AGE-2723] x-tfg-mcp-headers: Authorization skips MCP consent, forwarded (OSS) / mapped to x-tfy-mcp-headers (TFY) Nov 10, 2026

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Stale Bugbot comment from a previous run.

@rutvij-menavlikar
rutvij-menavlikar force-pushed the rutvij/age-2723_1 branch 2 times, most recently from 9c5e000 to 4be02c1 Compare November 10, 2026 11:18
@rutvij-menavlikar rutvij-menavlikar changed the title [AGE-2723] x-tfg-mcp-headers: Authorization skips MCP consent, forwarded (OSS) / mapped to x-tfy-mcp-headers (TFY) [AGE-2723] x-tfg-mcp-headers: pass MCP credentials, skip consent, fall back to auth flow on 401 Nov 10, 2026

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Stale Bugbot comment from a previous run.

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Stale Bugbot comment from a previous run.

…h 401 fallback (AGE-2723)

Co-authored-by: Cursor <cursoragent@cursor.com>
# Conflicts:
#	packages/trueforge/src/apis/turns.ts

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Stale Bugbot comment from a previous run.

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Stale Bugbot comment from a previous run.

Comment thread .changeset/mcp-401-auth-urls.md Resolved

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Stale Bugbot comment from a previous run.

…ndry details out of general tests (AGE-2723)

Co-authored-by: Rutvij Menavlikar <rutvij-menavlikar@users.noreply.github.com>
@truefoundry truefoundry deleted a comment from cursor Bot Nov 16, 2026
…-2723)

Co-authored-by: Rutvij Menavlikar <rutvij-menavlikar@users.noreply.github.com>

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 408c61d. Configure here.

cursoragent and others added 3 commits November 16, 2026 06:25
…ry/ (AGE-2723)"

This reverts commit 408c61d.

Co-authored-by: Rutvij Menavlikar <rutvij-menavlikar@users.noreply.github.com>
… TrueFoundry details out of general tests (AGE-2723)"

This reverts commit 5f8755e.

Co-authored-by: Rutvij Menavlikar <rutvij-menavlikar@users.noreply.github.com>
…undry tests out (AGE-2723)

Co-authored-by: Rutvij Menavlikar <rutvij-menavlikar@users.noreply.github.com>

@chiragjn chiragjn left a comment

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.

Adding initial comments

Comment thread packages/trueforge/src/resolvers.ts Outdated
Comment on lines +138 to +145
if (input.perServerHeaders !== undefined) {
return new McpServerWithAuthStore<TTransaction>({
store: options.persistenceStore,
tokenStore: options.tokenStore,
clientName: configuration.MCP_DCR_OAUTH_CLIENT_NAME,
perServerHeaders: input.perServerHeaders,
});
}

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 don't we pass perServerHeaders: input.perServerHeaders, to line 118

const withAuthMcpPersistenceStore = new McpServerWithAuthStore<TTransaction>({

itself?

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

withAuthMcpPersistenceStore is built once in buildResolveMcpServerStore and shared by every request, but x-tfg-mcp-headers is per request. Passing it there would leak one caller's headers into other requests. So a request carrying the header gets its own cheap instance (the constructor does no I/O), and requests without it reuse the shared one.

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: that store is created once and shared by all requests, but x-tfg-mcp-headers belongs to one request. Passing it there would send one caller's headers to other callers. So we create a new (cheap) store only when a request has the header.

Comment on lines +157 to +159
if (error instanceof McpConnectionError) {
return error.statusCode === 401;
}

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.

}

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.

cursoragent and others added 2 commits November 16, 2026 11:57
…and move caller-header merging out of db/

- Open-source x-tfg-mcp-headers is a flat map per server; nested virtual MCP entries parse only in TrueFoundry mode (truefoundry/virtualMcpHeaders.ts).
- McpServerWithAuthStore supplies its registered and configured headers; runtime/perServerMcpHeaders.ts withCallerMcpHeaders merges caller headers over them.
- Rename override helpers: overrideHeaders -> mergeCallerHeaders, resolveWithOverride -> resolveWithCallerHeaders.

Co-authored-by: Rutvij Menavlikar <rutvij-menavlikar@users.noreply.github.com>
…ent URLs or fails (AGE-2723)

Co-authored-by: Rutvij Menavlikar <rutvij-menavlikar@users.noreply.github.com>
@cursor cursor Bot changed the title [AGE-2723] x-tfg-mcp-headers: pass MCP credentials, skip consent, fall back to auth flow on 401 [AGE-2723] x-tfg-mcp-headers: pass MCP credentials and skip consent Nov 16, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants