Authentication and Security

1. Authentication access to Gateway using Truefoundry Token or your IDP token: Any user/application requires a token to talk to the gateway - so that the gateway can identify the user and subsequently impose authorization rules on the user. This can either be a Truefoundry API key or your own IdP token. Truefoundry AI Gateway can verify your own IdP token and extract the user’s email from the token based on the SSO settings.
2. Access Control at the Gateway layer: You can define at the gateway layer which users have access to which MCP servers. This allows fine-grained access control at an enterprise level. This is done via the MCP Server Group, wherein you can define the managers who can manage and give others access to the MCP servers.

3. External service authorization (MCP Server auth): This is the authorization implemented by the MCP Server for accessing the external service. Truefoundry allows MCP servers to be integrated with the following auth mechanisms:
   No Auth

   In this case, the MCP server can be accessed by anyone. This can be the case for demo APIs, or APIs that can be public like a Calculator MCP Server or Deepwiki MCP server(https://mcp.deepwiki.com/mcp)

   This is not recommended for any production MCP server or servers that provide access to some data.

   Static Header Based Auth

   Static Header-Based Auth allows you to set specific headers that will be passed to the MCP Server when the MCP Gateway forwards the request to the MCP Server.For example, when integrating the Hugging Face MCP server, you can define the Hugging Face Token as the value of Authorization the header.Users will connect to the MCP Gateway using a TrueFoundry Token or your IDP token. MCP Gateway will forward the request, along with all the headers defined, to the Hugging Face MCP server after a successful RBAC check.

   Header Based Auth are used by MCP servers that don’t support user-specific authentication methods like Oauth2 and instead have a static API key or token. In this case, all users calling the MCP server will use the same token.

   Oauth2 and DCR Based Auth

   In this case, every user will have their own token and the MCP server will grant access to only the resources that the user has access to. Oauth2 is supported by many of the popular MCP servers like Slack, Github, Atlassian, etc.

   Oauth based authentication is highly recommended for production MCP servers since it allows you to configure scopes to restrict access (e.g., read-only), unlike header authentication. OAuth2 allows users to revoke their own authorization, and users can only access resources they are permitted to use.

   To add an Oauth based MCP server to the AI Gateway and use it in the playground, follow the steps below:

   1

   Create an OAuth2 app in your provider's developer portal (e.g., GitHub, Google, etc.)

   • Set the redirect URI to:
     Copy

     Ask AI

     https://<tfy-control-plane-base-url>/api/svc/v1/llm-gateway/mcp-servers/oauth2/callback
     

     Replace <tfy-control-plane-base-url> with your TrueFoundry control plane URL.
   • Note your OAuth2 App ID, Secret, and required scopes.

   2

   Register your MCP Server in the AI Gateway

   • In the MCP Servers tab, click Add New MCP Server Group.
   • Click Add MCP Server and provide:
     • Endpoint URL: The URL of your deployed MCP Server
     • Authentication Type: Select OAuth2
     • OAuth2 App ID: The client ID from your OAuth2 app
     • OAuth2 App Secret: The client secret from your OAuth2 app
     • OAuth2 App Scopes: The required scopes for accessing provider resources

   For enhanced security, store your OAuth2 credentials in the TrueFoundry secrets store and reference their FQN in your configuration.

   3

   Using OAuth2 Authentication

   You can use the AI Gateway or MCP Gateway API to test and interact with your MCP Server using LLMs and tools.

   1. Click Add Tool/MCP Servers in the AI Gateway UI.
   2. For MCP Servers using OAuth2, click Connect Now to authorize the AI Gateway with your credentials.

   

   Authorize your MCP Server in AI Gateway

   • You can revoke your OAuth2 authorization at any time through the AI Gateway.

   

   Revoke your OAuth2 authorization

   3. Once authentication is successful, your MCP Server’s tools will appear in the list.

   

   MCP Server listed after authentication

   4. Select the tools you want to use and click Done.

4. Passing custom headers: You can pass any custom headers to MCP servers using the x-tfy-mcp-headers header. This is useful for authentication tokens, metadata, or any headers your MCP server needs.
   Remote MCP Server

   Virtual MCP Server

   Copy

   Ask AI

   import json
   from fastmcp import Client
   from fastmcp.client.transports import StreamableHttpTransport
   
   # Pass headers for a remote MCP server (flat structure)
   headers = json.dumps({"Authorization": "Bearer your-token"})
   
   transport = StreamableHttpTransport(
       url="https://{controlPlaneURL}/mcp/{groupName}/{mcpServerName}/server",
       headers={"x-tfy-mcp-headers": headers},
       auth="Bearer your-tfy-token"
   )
   

   For virtual MCP servers, the key is the server short FQN of each remote MCP server. Since virtual MCP servers contain multiple remote MCP servers, you can copy the FQN of each remote server from the UI (e.g., sample-mcp-group/server-1).
   Custom headers always override the default authentication configured for the MCP server.

MCP Gateway Authentication and Authorization Flow

​

Key Use Cases

​

1. Truefoundry Users accessing Oauth Based MCP servers

​

2. End customers accessing Oauth Based MCP Servers

​

3. Developers / End Customers accessing Bearer Token Based MCP servers