Skip to main content
TrueFoundry AI Gateway provides a comprehensive authentication and authorization system that separates how users authenticate to the Gateway (inbound authentication) from how the Gateway authenticates to downstream MCP servers (outbound authentication). This separation lets administrators choose the right security posture per tool without forcing end users to manage multiple credentials.

​
Authentication Architecture Overview

The Gateway provides a three-part authentication and authorization system:
ComponentDescription
Inbound AuthenticationHow clients (AI agents, developers, end users) authenticate to the Gateway
Access ControlRole-based policies determine which users can access which MCP servers and tools
Outbound AuthenticationHow the Gateway authenticates to downstream MCP servers
MCP Gateway Authentication and Authorization Flow

​
Inbound Authentication

Inbound authentication controls how clients authenticate to the Gateway. Any user or application requires valid credentials to talk to the Gateway, which allows the Gateway to identify the caller and apply authorization rules. TrueFoundry supports the following inbound authentication methods:
For internal developers and applications with TrueFoundry accounts. Users generate a Personal Access Token (PAT) from the TrueFoundry UI.
1

Generate a Personal Access Token

  1. Navigate to Settings > API Keys in the TrueFoundry UI
  2. Click Generate New API Key
  3. Store the token securely
2

Use the token in requests

from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport

transport = StreamableHttpTransport(
    url="https://<control-plane-url>/api/llm/mcp/<integration-id>/server",
    headers={"Authorization": "Bearer <your-tfy-api-key>"}
)

async with Client(transport) as client:
    result = await client.call_tool("tool_name", {"arg": "value"})
Virtual Accounts are service accounts with specific permissions to access MCP servers. Use Virtual Accounts when you need a shared token for server-to-server communication or when building applications where individual user identity isn’t required at the Gateway level.
1

Create a Virtual Account

  1. Navigate to Settings > Virtual Accounts in the TrueFoundry UI
  2. Click Create Virtual Account
  3. Give it a descriptive name (e.g., my-agent-mcp-access)
  4. Add permissions for the MCP servers your application needs to access
2

Generate and use the token

from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport

# Virtual Account token - same for all requests from your application
VA_TOKEN = "your-virtual-account-token"

transport = StreamableHttpTransport(
    url="https://<control-plane-url>/api/llm/mcp/<integration-id>/server",
    headers={"Authorization": f"Bearer {VA_TOKEN}"}
)

async with Client(transport) as client:
    result = await client.call_tool("tool_name", {"arg": "value"})
Virtual Account tokens provide the same level of access for all requests. For MCP servers that require user-specific access (like accessing a user’s GitHub repositories), use OAuth2 with individual user tokens instead.
For end customers or when you want to use your own identity provider (Okta, Azure AD, Auth0, Cognito, etc.). The AI Gateway validates your IdP token and extracts the user’s identity based on your SSO settings.This approach is ideal for:
  • B2B SaaS applications where your customers don’t have TrueFoundry accounts
  • Applications that want to use their existing identity infrastructure
  • Customer Identity and Access Management (CIAM) scenarios
1

Configure SSO Integration

Register your IdP with TrueFoundry:
  1. Navigate to Settings > SSO
  2. Create a new SSO configuration pointing to your IdP
  3. Important: Set login enabled to false (this SSO is only for external identity, not platform login)
  4. Note the SSO FQN for the next step
2

Create External Identity

Create an External Identity that maps JWTs from your IdP to TrueFoundry access:
  1. Navigate to Access > External Identities
  2. Click Add External Identity
  3. Select the SSO FQN from step 1
  4. Optionally add claims to match specific users/tenants
For detailed instructions, see Setup External Identity.
3

Grant MCP server access

Add the External Identity as a collaborator on the MCP server:
  1. Navigate to the MCP server’s settings
  2. Go to Collaborators
  3. Add the External Identity with appropriate permissions
4

Use your IdP token in requests

When your end user logs into your platform, your application receives their JWT. Use that JWT to authenticate with the Gateway:
from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport

# JWT from your IdP (e.g., Auth0, Okta)
user_jwt = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

transport = StreamableHttpTransport(
    url="https://<control-plane-url>/api/llm/mcp/<integration-id>/server",
    headers={"Authorization": f"Bearer {user_jwt}"}
)

async with Client(transport) as client:
    result = await client.call_tool("tool_name", {"arg": "value"})
TrueFoundry OAuth enables IDE tools like Cursor and VS Code to connect to the MCP Gateway using OAuth 2.0 authentication provided by TrueFoundry. This allows seamless authentication without requiring users to manually generate or manage API keys.When to use TrueFoundry OAuth:
  • Connecting to MCP servers from Cursor, VS Code, or other MCP-compatible IDEs
  • Enabling team members to access MCP tools without sharing or managing API keys
  • Leveraging existing TrueFoundry user authentication for MCP access
How it works:When you connect to an MCP server from your IDE using the Gateway URL, TrueFoundry automatically initiates an OAuth flow:
  1. The IDE prompts you to authenticate with TrueFoundry
  2. You sign in using your TrueFoundry credentials (or SSO if configured)
  3. TrueFoundry issues an OAuth token that the IDE uses for subsequent requests
  4. No manual token configuration is required
TrueFoundry OAuth tokens can be used in combination with Token Forwarding (outbound) to pass additional MCP server-specific headers alongside the OAuth token.

​
Access Control

Once authenticated, the Gateway verifies whether the user has permission to access the requested MCP server and tools. MCP Server Access Control Access control is enforced based on the user’s identity (TrueFoundry user, Virtual Account, or External Identity). You can define granular permissions for:
  • Which MCP servers a user can access
  • Which tools within an MCP server a user can invoke
You can also create a Virtual MCP Server to expose a subset of tools from different MCP servers and grant access to specific users or teams.

​
Outbound Authentication

Outbound authentication controls how the Gateway authenticates to downstream MCP servers. TrueFoundry supports multiple authentication models to handle different MCP server requirements.
No Auth: The MCP server doesn’t require any authentication. Suitable for:
  • Demo or sandbox APIs
  • Public tools like a Calculator MCP Server or DeepWiki MCP server
Not recommended for production MCP servers or any server that provides access to sensitive data.
API Key (Static Headers): The MCP server requires a static API key or token that is the same for all requests. You configure this credential once, and the Gateway injects it into every request regardless of which end user is calling.When to use shared service accounts:
  • Datasets meant for broad team or department access
  • Read-only access to shared resources (knowledge bases, analytics)
  • Legacy systems without per-user OAuth support
  • Internal tools where a service account is easier to audit
Example: A Hugging Face MCP server uses a shared API token. Users connect through the Gateway with their TrueFoundry credentials, while the Gateway injects the shared token and enforces which models or datasets each role can access.
The MCP server requires end-user-specific OAuth tokens to access external services like GitHub, Slack, or Atlassian. Each end user must complete an OAuth consent flow to grant access to their resources on those services.When to use per-user OAuth:
  • Personal productivity tools (email, calendar, documents)
  • Systems where permissions differ per user
  • Actions that must be attributed to an individual
How OAuth 2.1 works:
  1. End user authenticates with the Gateway (using TrueFoundry token or External Identity)
  2. End user attempts to call an MCP tool → Gateway returns auth error with authorization URL
  3. End user visits URL and completes OAuth consent on the third-party service (e.g., GitHub)
  4. TrueFoundry stores the OAuth token for that end user
  5. Future requests automatically include the end user’s OAuth token
Example: A Slack MCP server prompts each employee to authorize their account during first use. TrueFoundry stores the OAuth refresh token, rotates it automatically, and injects it only when that user invokes a Slack tool. Each user can only access their own messages and channels.
Key point: With OAuth 2.1, end users authenticate twice - once with the Gateway (inbound), and once with the third-party service (GitHub, Slack, etc.) to grant access to their resources there (outbound).
The incoming token used for inbound authentication (TrueFoundry token or External IdP token) is forwarded directly to the MCP server. The MCP server validates and uses this token for authorization.When to use Token Passthrough:
  • Your MCP server trusts the same IdP that authenticated the user to the Gateway
  • The MCP server is configured to validate TrueFoundry tokens or your IdP’s JWTs
  • You want the MCP server to make authorization decisions based on the user’s identity
How Token Passthrough works:
  1. User authenticates to the Gateway with their token (TrueFoundry or IdP)
  2. Gateway validates the token and checks access control
  3. Gateway forwards the same token to the MCP server
  4. MCP server validates the token and processes the request
Example: An internal MCP server that connects to your organization’s services validates the user’s IdP token to ensure they have access to specific resources based on their role claims.
Key point: Token Passthrough is ideal when your MCP server needs to know the user’s identity and can validate tokens from TrueFoundry or your IdP.
Token Forwarding allows clients to pass additional headers to MCP servers using the x-tfy-mcp-headers header. This is useful when the MCP server requires specific authentication tokens or metadata that are different from the Gateway authentication.When to use Token Forwarding:
  • The MCP server requires a specific token format that differs from Gateway authentication
  • You need to pass additional metadata or authentication headers
  • The client has direct credentials for the MCP server
How Token Forwarding works:
  1. Client authenticates to the Gateway with TrueFoundry token or IdP token (inbound auth)
  2. Client includes x-tfy-mcp-headers with additional headers for the MCP server
  3. Gateway validates the inbound token and checks access control
  4. Gateway forwards the custom headers to the MCP server
import json
from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport

# Pass headers for a remote MCP server (flat structure)
mcp_headers = json.dumps({"Authorization": "Bearer mcp-server-token"})

transport = StreamableHttpTransport(
    url="https://<control-plane-url>/api/llm/mcp/<integration-id>/server",
    headers={
        "Authorization": "Bearer <your-tfy-api-key>",  # Inbound auth
        "x-tfy-mcp-headers": mcp_headers  # Outbound auth - forwarded to MCP server
    }
)

async with Client(transport) as client:
    result = await client.call_tool("tool_name", {"arg": "value"})
For virtual MCP servers, use the remote MCP server identifier as the key (e.g., server-1). Copy the identifier from the UI since virtual MCP servers contain multiple remote MCP servers.
Custom headers from x-tfy-mcp-headers always override the default authentication configured for the MCP server.

​
Outbound Authentication Summary

TrueFoundry MCP Gateway supports registering MCP servers with different outbound authentication models. The Gateway keeps the user-facing experience consistent even when different MCP servers use different authentication models.
MCP ServerOutbound AuthReason
Gmail, Slack, GitHubOAuth 2.1Personal data, user-specific permissions
Hugging Face, DeepWikiNo Auth / API KeyPublic or shared access
Internal MCP Server with IdP authToken PassthroughMCP server validates user’s IdP token
Internal MCP Server from OpenAPIToken ForwardingClient provides MCP server credentials

​
Authentication Scenarios

The following scenarios show how different combinations of inbound and outbound authentication work in practice. Each scenario includes a sequence diagram and a detailed step-by-step breakdown.

​
Scenario 1: TrueFoundry API Key + OAuth 2.1 Outbound

Inbound: TrueFoundry API Key | Outbound: OAuth 2.1 Use case: Internal developers with TrueFoundry accounts accessing OAuth-protected services like Slack, GitHub, or Atlassian. This is the most common enterprise scenario where your developers authenticate to TrueFoundry and the Gateway handles OAuth token management for downstream MCP servers. Sequence Diagram for Truefoundry User accessing Oauth Based MCP Servers
StepActionDescription
1User → Control PlaneUser logs into TrueFoundry
2Control Plane → IdPTrueFoundry redirects to your identity provider (Okta, Azure AD, etc.)
3IdP → UserUser authenticates and receives IdP access token
4User → Control PlaneUser initiates OAuth flow for the MCP server (e.g., “Connect to Atlassian”)
5Control PlaneVerifies user has permission to access this MCP server
6Control Plane → External ProviderUser is redirected to the external service (e.g., Atlassian) to authorize access
7External Provider → Control PlaneExternal service returns OAuth tokens after user approval
8Control PlaneSecurely stores access and refresh tokens, linked to the user’s identity
StepActionDescription
1Agent → GatewayAI Agent sends request with TrueFoundry token (inbound auth)
2GatewayValidates the TrueFoundry token
3GatewayChecks if the token has access to the requested MCP server/tool
4Gateway → Control Plane(If not cached) Retrieves user’s OAuth token for this MCP server
5GatewayCaches the OAuth token for subsequent requests
6Gateway → MCP ServerForwards request with the user’s OAuth token (outbound auth)
7MCP Server → External ProviderValidates token and fetches user-specific data
8MCP Server → AgentReturns response through the Gateway
Key benefits of this flow:
  • Users authenticate once to TrueFoundry and access multiple OAuth-protected services
  • Tokens are automatically refreshed when they expire
  • Each user’s actions are attributed to their individual identity
  • Users can revoke access to specific services at any time

​
Scenario 2: External IdP Token + OAuth 2.1 Outbound (CIAM)

Inbound: External IdP Token | Outbound: OAuth 2.1 Use case: Your end customers (who don’t have TrueFoundry accounts) accessing OAuth-protected services through your application. This scenario is common for Customer Identity and Access Management (CIAM) where you want your customers to connect their own accounts (e.g., their Gmail, Slack, or CRM) to your AI-powered application. Sequence Diagram for End customers accessing Oauth Based MCP Servers
StepActionDescription
1User → IdPUser logs into your identity provider directly (not TrueFoundry)
2IdP → UserUser receives IdP access token
3User → Control PlaneUser initiates OAuth flow for the MCP server
4Control PlaneValidates the IdP token and extracts user identity (inbound auth)
5Control PlaneChecks if the user/role has access to this MCP server
6Control Plane → External ProviderRedirects user to authorize access (3-legged OAuth)
7External Provider → Control PlaneReturns OAuth tokens; Control Plane stores them securely
StepActionDescription
1Agent → GatewayAI Agent sends request with IdP token (inbound auth)
2GatewayValidates the IdP token using your SSO configuration
3GatewayChecks if the extracted user identity has access to the MCP server/tool
4Gateway → Control Plane(If not cached) Retrieves the user’s OAuth token using their IdP identity
5GatewayCaches the OAuth token for performance
6Gateway → MCP ServerForwards request with user’s OAuth token (outbound auth)
7MCP Server → External ProviderValidates and processes the request
8MCP Server → AgentReturns response through the Gateway
Key differences from Scenario 1:
  • Users authenticate with your IdP, not TrueFoundry (different inbound auth)
  • The Gateway validates your IdP tokens directly
  • Useful for B2B SaaS applications with end-customer integrations
You can also use this method for internal developers if you prefer not to use TrueFoundry tokens and want to leverage your existing identity infrastructure.

​
Scenario 3: TrueFoundry/IdP Token + API Key Outbound

Inbound: TrueFoundry API Key or External IdP Token | Outbound: No Auth / API Key Use case: Accessing MCP servers with shared credentials where individual user identity at the downstream service is not required. This scenario is ideal for read-only access to shared resources, internal tools, or services that don’t support per-user OAuth. Sequence Diagram for Developers / End Customers accessing Bearer Token Based MCP servers
StepActionDescription
1Admin → Control PlaneAdministrator registers the MCP server with static header authentication (outbound)
2AdminConfigures the shared API key or bearer token in the MCP server settings
3AdminDefines which users/roles have access to this MCP server through RBAC policies
The shared credentials are stored securely and never exposed to end users.
StepActionDescription
1Agent → GatewayAI Agent sends request with user’s TrueFoundry or IdP token (inbound auth)
2GatewayValidates the user token
3GatewayChecks if the user has access to this MCP server (RBAC)
4GatewayInjects the shared credentials (static headers) into the request (outbound auth)
5Gateway → MCP ServerForwards request with shared service account credentials
6MCP ServerProcesses request using the shared credentials
7MCP Server → AgentReturns response through the Gateway
Security considerations:
  • All users share the same level of access to the downstream service
  • Actions cannot be attributed to individual users at the downstream service level
  • TrueFoundry’s audit logs still track which user made each request at the Gateway level

​
Scenario 4: Token Passthrough (Inbound Token Forwarded to MCP Server)

Inbound: TrueFoundry API Key or External IdP Token | Outbound: Token Passthrough Use case: Accessing MCP servers that validate the same token used for Gateway authentication. This scenario is for organizations where the MCP server itself can validate the user’s TrueFoundry token or IdP JWT.
StepActionDescription
1Configure Inbound AuthSet up TrueFoundry API Key or External Identity
2Register MCP ServerRegister the MCP server with Token Passthrough as outbound authentication
3Configure MCP ServerEnsure the MCP server is configured to validate TrueFoundry tokens or your IdP’s JWTs
StepActionDescription
1User → IdP/TrueFoundryUser authenticates and receives a token
2Agent → GatewayAI Agent sends request with user’s token (inbound auth)
3GatewayValidates the token
4GatewayChecks if the user has access to this MCP server (RBAC)
5Gateway → MCP ServerForwards request with user’s token unchanged (outbound: token passthrough)
6MCP ServerValidates the token and processes the request
7MCP Server → AgentReturns response through the Gateway
When to use Token Passthrough:
  • Your MCP server can validate TrueFoundry tokens or your IdP’s JWTs
  • You want the MCP server to know the user’s identity
  • The MCP server makes authorization decisions based on token claims

​
Scenario 5: Token Forwarding (Custom MCP Server Headers)

Inbound: TrueFoundry API Key or External IdP Token | Outbound: Token Forwarding Use case: The client has specific credentials for the MCP server that are different from the Gateway authentication token. This scenario is useful when the MCP server requires its own authentication that cannot be managed by the Gateway (e.g., internal APIs with their own token systems).
StepActionDescription
1Configure Inbound AuthSet up TrueFoundry API Key or External Identity
2Register MCP ServerRegister the MCP server (no outbound auth configured, or Token Forwarding mode)
3Client ConfigurationClient must include x-tfy-mcp-headers with MCP server credentials
StepActionDescription
1Agent → GatewayAI Agent sends request with TrueFoundry/IdP token + x-tfy-mcp-headers
2GatewayValidates the inbound token
3GatewayChecks if the user has access to this MCP server (RBAC)
4GatewayExtracts headers from x-tfy-mcp-headers
5Gateway → MCP ServerForwards request with extracted headers (outbound auth)
6MCP ServerValidates the custom headers and processes the request
7MCP Server → AgentReturns response through the Gateway
When to use Token Forwarding:
  • The MCP server has its own authentication system separate from Gateway authentication
  • You need to pass user-specific tokens that the client manages
  • The MCP server requires additional metadata alongside authentication

​
Choosing the Right Authentication Model

For code examples, see Using MCP Gateway in Your Agent.

​
Quick Reference

Inbound Authentication (client → Gateway):
  • TrueFoundry API Key: Internal developers with TrueFoundry accounts
  • External IdP Token: End customers authenticating via your IdP (B2B SaaS, CIAM)
  • TrueFoundry OAuth: Third-party apps needing delegated user access
Outbound Authentication (Gateway → MCP server):
  • OAuth 2.1: Per-user access to third-party services (Gmail, Slack, GitHub)
  • API Key / No Auth: Shared resources or public APIs (Hugging Face, DeepWiki)
  • Token Passthrough: Internal MCP servers that validate your IdP tokens
  • Token Forwarding: MCP servers with separate auth systems (client provides credentials via x-tfy-mcp-headers)

​
FAQ

  • Inbound Authentication: How clients (AI agents, developers, end users) prove their identity to the Gateway. This determines who is making the request.
  • Outbound Authentication: How the Gateway authenticates to downstream MCP servers. This determines how the MCP server trusts and processes the request.
These two are independent - you can mix and match based on your requirements. For example, a client might authenticate with their IdP token (inbound) while the Gateway uses OAuth 2.1 to access the user’s GitHub (outbound).
Use this quick reference to decide between OAuth 2.1 and Token Passthrough:
QuestionIf Yes →
Does the MCP server connect to third-party services (GitHub, Slack, Google, etc.)?OAuth 2.1
Does the MCP server validate the same token used for inbound auth?Token Passthrough
OAuth 2.1 is for when users need to authorize access to their accounts on external services. The Gateway manages the OAuth flow and stores tokens.Token Passthrough is for when the MCP server trusts your IdP or TrueFoundry and can validate the inbound token directly.
  • Token Passthrough: The Gateway forwards the same token used for inbound authentication to the MCP server. The MCP server must be able to validate TrueFoundry tokens or your IdP tokens.
  • Token Forwarding: The client provides separate credentials for the MCP server via x-tfy-mcp-headers. These are different from the inbound auth token and are forwarded as-is to the MCP server.
Use Token Passthrough when your MCP server trusts your existing identity provider. Use Token Forwarding when the MCP server has its own authentication system that doesn’t recognize your inbound tokens.
Yes. The Gateway validates any supported inbound auth method (TrueFoundry API Key, External IdP Token, or TrueFoundry OAuth). Access control is then applied based on the authenticated identity. This means you can have some users authenticate with TrueFoundry tokens and others with IdP tokens, as long as both have appropriate permissions.