Authentication and Security

• 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
• Service-to-service authentication where the caller already holds an IdP-issued JWT

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

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

transport = StreamableHttpTransport(
    url="{GATEWAY_BASE_URL}/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"})

• 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

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

• Demo or sandbox APIs
• Public tools like a Calculator MCP Server or DeepWiki MCP server

• Shared Credentials: One key is used by everyone. You configure the credential once, and the Gateway injects it into every request regardless of which end user is calling.
• Individual Credentials: Each user provides their own key. Users must supply their own API key through Auth Overrides before they can use the MCP server. The Gateway injects the user-specific key into requests.

​

Authorization Code

1. End user authenticates with the Gateway (using a TrueFoundry token or an Identity Provider token)
2. End user attempts to call an MCP tool → Gateway returns an auth error with the authorization URL
3. End user visits the 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

​

Client Credentials

1. The Gateway sends the client ID and secret to the provider’s token endpoint
2. The provider returns an access token
3. The Gateway uses this token to authenticate requests to the MCP server
4. Tokens are automatically refreshed when they expire

• 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

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

• 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

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

• An internal support bot that queries your company’s knowledge base
• A code assistant that uses a shared GitHub service account
• A data analysis agent that accesses shared analytics databases

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

VA_TOKEN = os.environ["VIRTUAL_ACCOUNT_TOKEN"]

async def call_tool_as_service():
    transport = StreamableHttpTransport(
        url="https://<gateway-url>/mcp/<server-name>/server",
        headers={"Authorization": f"Bearer {VA_TOKEN}"}
    )

    async with Client(transport) as client:
        result = await client.call_tool("query_knowledge_base", {"question": "..."})
        return result

• A productivity agent that accesses the user’s own Gmail, Slack, or Calendar
• A development assistant that accesses the user’s GitHub repositories
• A CRM agent that sees only what the logged-in user can see

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

async def call_tool_as_user(user_token: str):
    transport = StreamableHttpTransport(
        url="https://<gateway-url>/mcp/<server-name>/server",
        headers={"Authorization": f"Bearer {user_token}"}
    )

    async with Client(transport) as client:
        result = await client.call_tool("search_emails", {"query": "..."})
        return result

• An assistant that searches the web (shared API key) and sends emails on the user’s behalf (per-user OAuth)
• A dev tool that queries documentation (shared) but accesses the user’s GitHub (per-user)

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

async def call_mixed_tools(user_token: str):
    transport = StreamableHttpTransport(
        url="https://<gateway-url>/mcp/<virtual-mcp-name>/server",
        headers={"Authorization": f"Bearer {user_token}"}
    )

    async with Client(transport) as client:
        # Web search uses shared API key (configured on MCP server)
        await client.call_tool("web_search", {"query": "..."})

        # Gmail uses user's OAuth token (user must have completed OAuth)
        await client.call_tool("send_email", {"to": "...", "body": "..."})

• 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

• 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

• 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

• 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

• 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

• 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.

1. Use a TrueFoundry PAT or a JWT from a configured Identity Provider for per-user OAuth
2. Configure the MCP server with Static Header (shared) auth instead

• Verify your authentication token is valid and not expired
• Check that you have access to the MCP server (see collaborators in UI)
• For Virtual Accounts, ensure the account has the required permissions
• For OAuth-protected servers, the user may need to complete the OAuth consent flow first — see Handling OAuth-protected MCP servers

• List available tools using client.list_tools() to confirm what’s exposed
• Tool names are case-sensitive
• The MCP server may have been updated — refresh the tool list