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 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.
Add MCP Servers 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.
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 Apply 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
List MCP Servers You can list and retrieve MCP Servers using the List Provider Integrations API. This allows you to query existing MCP server integrations with filtering and pagination support.
API Overview Here is the curl command example to list MCP Servers:
curl -X GET "YOUR_CONTROL_PLANE_URL/api/svc/v1/provider-integrations?type=mcp-server" \ -H "accept: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" Query Parameters type
string
default: "mcp-server"
Filter integrations by type. For MCP servers, use mcp-server.
Filter by fully qualified name (FQN) of a specific integration. Cannot be used with id.
Filter by integration ID. Cannot be used with fqn.
Pagination offset - number of items to skip.
Maximum number of items to return. If not specified, returns all items.
Response Schema { "data" : [ { "id" : "integration-456" , "name" : "my-mcp-server" , "fqn" : "truefoundry:mcp-server-group:my-mcp-server-group:mcp-server:my-mcp-server" , "type" : "mcp-server" , "manifest" : { "url" : "https://mcp-server.example.com" , "name" : "my-mcp-server" , "type" : "integration/mcp-server/remote" , "description" : "A sample MCP server for file operations" , "authorized_subjects" : [ "team:everyone" ] }, "metadata" : {}, "providerAccountFqn" : "truefoundry:mcp-server-group:my-mcp-server-group" , "providerAccount" : { "id" : "mcp-provider-account-123" , "name" : "my-mcp-server-group" , "fqn" : "truefoundry:mcp-server-group:my-mcp-server-group" , "provider" : "mcp-server-group" , "manifest" : { "name" : "my-mcp-server-group" , "type" : "provider-account/mcp-server-group" , "collaborators" : [ { "role_id" : "provider-account-manager" , "subject" : "user:user@example.com" }, { "role_id" : "provider-account-manager" , "subject" : "team:everyone" } ] }, "createdBySubject" : { "subjectId" : "user-123" , "subjectType" : "user" , "subjectSlug" : "user@example.com" , "subjectPatName" : null , "subjectDisplayName" : "John Doe" }, "createdAt" : "2024-01-15T10:30:00.000Z" , "updatedAt" : "2024-01-15T10:30:00.000Z" , "createdBy" : "user@example.com" }, "createdBySubject" : { "subjectId" : "user-123" , "subjectType" : "user" , "subjectSlug" : "user@example.com" , "subjectPatName" : "user-pat-1" , "subjectDisplayName" : "John Doe" }, "createdAt" : "2024-01-15T10:30:00.000Z" , "updatedAt" : "2024-01-15T10:30:00.000Z" , "createdBy" : "user@example.com" } ], "pagination" : { "total" : 1 , "offset" : 0 , "limit" : 10 } } Response Fields Array of MCP server integration objects. Show Integration Object Properties
Unique identifier for the MCP server integration.
Name of the MCP server integration.
Fully qualified name of the integration in the format: tenant:mcp-server-group:account:mcp-server:name (colon-separated).
Type of the integration (e.g., “mcp-server”).
The MCP server integration manifest (auth_data is excluded for security).
Additional metadata associated with the integration.
FQN of the provider account this integration belongs to.
Full provider account object that contains this integration. Show Provider Account Properties
Unique identifier for the provider account.
Name of the provider account.
Fully qualified name of the provider account.
Provider type (e.g., “mcp-server-group”).
Provider account manifest including collaborators.
Information about the user who created the provider account.
Timestamp when the provider account was created.
Timestamp when the provider account was last updated.
ID of the user who created the provider account.
Information about the user who created the integration. Unique identifier for the subject.
Type of subject (e.g., “user”).
Slug identifier for the subject (e.g., email address).
Personal Access Token name if the action was performed using a PAT, or null.
Display name of the subject, or null if not available.
Timestamp when the integration was created.
Timestamp when the integration was last updated.
ID of the user who created the integration.
Pagination metadata. Show Pagination Properties
Total number of integrations matching the query.
Current pagination offset.
Maximum number of items returned per page.
Examples Show List All MCP Servers
To list all MCP server integrations in your tenant: curl -X GET "YOUR_CONTROL_PLANE_URL/api/svc/v1/provider-integrations?type=mcp-server" \ -H "accept: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" Show List MCP Servers with Pagination
To retrieve MCP servers with pagination (10 items starting from offset 20): curl -X GET "YOUR_CONTROL_PLANE_URL/api/svc/v1/provider-integrations?type=mcp-server&limit=10&offset=20" \ -H "accept: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" Show Get Specific MCP Server by FQN
To retrieve a specific MCP server by its fully qualified name: curl -X GET "YOUR_CONTROL_PLANE_URL/api/svc/v1/provider-integrations?type=mcp-server&fqn=truefoundry:mcp-server-group:my-mcp-server-group:mcp-server:my-mcp-server" \ -H "accept: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" Show Get Specific MCP Server by ID
To retrieve a specific MCP server by its integration ID: curl -X GET "YOUR_CONTROL_PLANE_URL/api/svc/v1/provider-integrations?type=mcp-server&id=integration-456" \ -H "accept: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" Error Handling The List API may return various error responses. Common scenarios include:
400 Bad Request : Invalid query parameters (e.g., both fqn and id provided)401 Unauthorized : Invalid or missing API key404 Not Found : Integration with specified id or fqn not found 
