TrueFoundry allows you to connect to external Model Context Protocol (MCP) servers that provide tools and capabilities for AI applications. Once Added, these MCP servers can be used in truefoundry AI gateway and your applications.
The MCP servers are saved as a provider Integrations in truefoundry. The group of MCP servers are saved as a provider account. You can add multiple MCP servers to a single provider account, the MCP servers in the same provider account are called integrations.
Replace YOUR_CONTROL_PLANE_URL with your actual TrueFoundry control plane
URL and YOUR_API_KEY with your API key throughout this guide.
API Overview Here is the curl command example to add an MCP Server:
curl -X PUT "YOUR_CONTROL_PLANE_URL/api/svc/v1/apply" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "manifest": { "type": "provider-account/hosted-mcp-server", "name": "my-mcp-server-group", "integrations": [ { "type": "integration/mcp-server/hosted-mcp-server", "name": "my-mcp-server", "description": "A sample MCP server for file operations", "url": "https://mcp-server.example.com", "auth_data": { "type": "header", "headers": { "Authorization": "Bearer your-token" } } } ] }, "dryRun": false }' Request Schema The Apply API accepts a TrueFoundryApplyRequest object with the following structure:
manifest
McpServerProviderAccount | ModelManifest | ArtifactManifest | Service | ...
required
The manifest object defining the resource to be created or updated. For MCP
Server integrations, this should be a McpServerProviderAccount object. See
McpServerProviderAccount
for the complete schema. When set to true, performs a dry run without actually creating or updating
the resource. Useful for validation.
McpServerProviderAccount Schema For adding MCP Servers, the manifest should be a McpServerProviderAccount object. For detailed schema information, refer to the McpServerProviderAccount type documentation.
Response Schema { "id" : "mcp-provider-account-123" , "name" : "my-mcp-server-group" , "fqn" : "tenant-name/hosted-mcp-server/my-mcp-server-group" , "provider" : "hosted-mcp-server" , "manifest" : { "type" : "provider-account/hosted-mcp-server" , "name" : "my-mcp-server-group" , "integrations" : [ { "type" : "integration/mcp-server/hosted-mcp-server" , "name" : "my-mcp-server" , "description" : "A sample MCP server for file operations" , "url" : "https://mcp-server.example.com" , "auth_data" : { "type" : "header" , "headers" : { "Authorization" : "Bearer your-token" } } } ] }, "integrations" : [ { "id" : "integration-456" , "name" : "my-mcp-server" , "fqn" : "tenant-name/hosted-mcp-server/my-mcp-server-group/integration/my-mcp-server" , "type" : "integration" , "manifest" : { "type" : "integration/mcp-server/hosted-mcp-server" , "name" : "my-mcp-server" , "description" : "A sample MCP server for file operations" , "url" : "https://mcp-server.example.com" , "auth_data" : { "type" : "header" , "headers" : { "Authorization" : "Bearer your-token" } } }, "providerAccountFqn" : "tenant-name/hosted-mcp-server/my-mcp-server-group" , "createdBySubject" : { "subjectSlug" : "user@example.com" }, "createdAt" : "2024-01-15T10:30:00Z" , "updatedAt" : "2024-01-15T10:30:00Z" } ], "createdBySubject" : { "subjectSlug" : "user@example.com" }, "createdAt" : "2024-01-15T10:30:00Z" , "updatedAt" : "2024-01-15T10:30:00Z" , "action" : "CREATE" } Response Fields Unique identifier for the MCP Server provider account.
Name of the MCP Server provider account.
Fully qualified name of the provider account (tenant/provider/name).
The provider type: “hosted-mcp-server”.
The MCP Server provider account manifest that was applied, excluding
integrations.
List of MCP Server integrations associated with this account.
Information about the user who created the provider account.
Timestamp when the provider account was created.
Timestamp when the provider account was last updated.
The action performed: “CREATE” for new resources, “UPDATE” for existing ones.
MCP Server Provider Account Examples Show Basic MCP Server with Header Authentication
For connecting to an MCP Server with header-based authentication: { "type" : "provider-account/hosted-mcp-server" , "name" : "my-mcp-server-group" , "integrations" : [ { "type" : "integration/mcp-server/hosted-mcp-server" , "name" : "file-server" , "description" : "MCP server for file operations" , "url" : "https://mcp-server.example.com" , "auth_data" : { "type" : "header" , "headers" : { "Authorization" : "Bearer your-token" , "X-API-Key" : "your-api-key" } } } ] } Show Public MCP Server (No Authentication)
For connecting to a public MCP Server without authentication: { "type" : "provider-account/hosted-mcp-server" , "name" : "public-mcp-servers" , "integrations" : [ { "type" : "integration/mcp-server/hosted-mcp-server" , "name" : "weather-server" , "description" : "Public weather data MCP server" , "url" : "https://weather-mcp.example.com" , "auth_data" : { "type" : "passthrough" } } ] } Show Multiple MCP Servers in One Group
For managing multiple related MCP Servers in a single provider account: { "type" : "provider-account/hosted-mcp-server" , "name" : "data-processing-servers" , "integrations" : [ { "type" : "integration/mcp-server/hosted-mcp-server" , "name" : "csv-processor" , "description" : "MCP server for CSV file processing and manipulation" , "url" : "https://csv-mcp.example.com" , "auth_data" : { "type" : "header" , "headers" : { "Authorization" : "Bearer csv-token" } } }, { "type" : "integration/mcp-server/hosted-mcp-server" , "name" : "json-processor" , "description" : "MCP server for JSON data processing and validation" , "url" : "https://json-mcp.example.com" , "auth_data" : { "type" : "header" , "headers" : { "Authorization" : "Bearer json-token" } } }, { "type" : "integration/mcp-server/hosted-mcp-server" , "name" : "xml-processor" , "description" : "MCP server for XML data processing and transformation" , "url" : "https://xml-mcp.example.com" , "auth_data" : { "type" : "passthrough" } } ] } Show MCP Server with OAuth2 Authentication
For connecting to an MCP Server with OAuth2 authentication: { "type" : "provider-account/hosted-mcp-server" , "name" : "oauth2-mcp-servers" , "integrations" : [ { "type" : "integration/mcp-server/hosted-mcp-server" , "name" : "secure-api-server" , "description" : "MCP server with OAuth2 authentication for secure API access" , "url" : "https://secure-mcp.example.com" , "auth_data" : { "type" : "oauth2" , "client_id" : "your-client-id" , "client_secret" : "your-client-secret" , "authorization_url" : "https://auth.example.com/oauth/authorize" , "token_url" : "https://auth.example.com/oauth/token" , "scopes" : [ "mcp:read" , "mcp:write" ], "jwt_source" : "idtoken" } } ] } Error Handling The API may return various error responses. Common scenarios include:
400 Bad Request : Invalid manifest structure or missing required fields401 Unauthorized : Invalid or missing API key403 Forbidden : Insufficient permissions for the operation404 Not Found : MCP Server provider account not found409 Conflict : MCP Server provider account with the same name already exists422 Unprocessable Entity : Invalid MCP Server configuration or connection issues 
