Skip to content

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

Merged
rutvij-menavlikar merged 41 commits into
mainfrom
rutvij/age-2723_1
Nov 18, 2026
Merged

rutvij-menavlikar merged 41 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 header composition, consent timing, and 401 handling for all remote MCP connections in both open-source and TrueFoundry modes.

Reviewed by Cursor Bugbot for commit 9695d62. 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 is an optional per-server header map on the TrueForge request; it may carry its own Authorization for that MCP server. It is unrelated to TrueForge request auth, which is never sent to the MCP server in open-source mode.

# Flat entry (both modes)
x-tfg-mcp-headers: {"github-mcp": {"Authorization": "Bearer <user-token>", "X-End-User": "alice"}}

# Nested virtual MCP entry (TrueFoundry mode only): one header map per underlying server
x-tfg-mcp-headers: {"virtual-mcp": {"serv1": {"Authorization": "Bearer a"}, "serv2": {"Authorization": "Bearer b"}}}

Malformed values, nested entries in open-source mode, and the managed mcp-session-id / mcp-protocol-version headers are rejected with 400.

Changes

Open-source mode

  • Registered headers: DCR → none if the entry has Authorization, else the stored access token (refreshed as needed); otherwise the manifest's static headers.
  • The entry is merged on top (entry wins on name clashes, including Authorization).
  • Before connecting (DCR only): no usable token and no entry Authorization → mcp.auth_required (DCR consent), as on main.
  • On a 401: entry Authorization → hard fail; else DCR → mcp.auth_required with a fresh DCR consent URL (the stored token is kept until the OAuth callback replaces it); else → hard fail.

TrueFoundry mode

  • Gateway Bearer plus turn metadata. Any entry for the server (flat or nested) is sent as x-tfy-mcp-headers; the gateway Authorization stays the gateway Bearer.
  • ServiceFoundry /authorize is no longer called before connecting.
  • On a 401: entry present → hard fail (no /authorize). No entry → /authorize: auth_required + URL → mcp.auth_required; auth_required without a URL → 422 as on main; authenticated / not_required → 422.
  • Verified against the gateway: with authorization in x-tfy-mcp-headers it skips its own token resolution and forwards an upstream 401 as-is, so such a 401 never means consent is needed.

Core (@truefoundry/trueforge-core)

  • ResolveHeadersResult gains an optional authRequiredOnUnauthorized hook. On a 401, RemoteMCP calls it once: consent → reset the rejected connection and return authRequired; undefined → rethrow the 401; a thrown error (e.g. the 422) propagates. No TrueFoundry-specific logic.

Other

  • perServerMcpHeaders moved from truefoundry/ to runtime/ since both modes use it; the TrueFoundry-only nested schema lives in truefoundry/virtualMcpHeaders.ts.
  • Standalone (sqlite) mode routes the MCP store through buildResolveMcpServerStore so the header is honored; the turn session header keeps the 401 hook.

How was this tested?

  • Core tests/core (361 passed): 401 with consent (at connect, mid-session with reconnect), no consent, lookup error propagates.
  • Trueforge tests/unit (938 passed): header parsing; open-source DCR skip, merge, DCR 401 hook kept without entry Authorization; TrueFoundry x-tfy-mcp-headers for any entry, no up-front authorize, 401 hook only without an entry, consent / 422 mappings, delegate and exchange token assertions.
  • Typecheck for both packages, eslint --max-warnings=0, prettier.

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: 9695d62

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
…723)

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.

Stale Bugbot comment from a previous run.

…E-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.

Stale Bugbot comment from a previous run.

…oken (AGE-2723)"

This reverts commit e36c89c.

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.

Stale Bugbot comment from a previous run.

rutvij-menavlikar and others added 3 commits November 17, 2026 20:28
…2723)

Co-authored-by: Cursor <cursoragent@cursor.com>
…E-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 e4449a4. Configure here.

@rutvij-menavlikar
rutvij-menavlikar enabled auto-merge (squash) November 18, 2026 09:10
cursoragent and others added 2 commits November 18, 2026 11:07
…dling (AGE-2723)

- callerHeaders -> serverOverrideHeaders, withCallerMcpHeaders -> withServerOverrideHeaders,
  mergeCallerHeaders -> mergeOverrideHeaders, registeredHeaders -> storeHeaders
- TrueFoundry 401 consent: if/else with clearer 422 messages
- RemoteMCP: explicit isAuthError branch before the recovery hook
Co-authored-by: Rutvij Menavlikar <rutvij-menavlikar@users.noreply.github.com>
@rutvij-menavlikar
rutvij-menavlikar enabled auto-merge (squash) November 18, 2026 12:18
@rutvij-menavlikar
rutvij-menavlikar merged commit 3050b24 into main Nov 18, 2026
13 checks passed
@rutvij-menavlikar
rutvij-menavlikar deleted the rutvij/age-2723_1 branch November 18, 2026 12:20
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