> ## Documentation Index > Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt > Use this file to discover all available pages before exploring further. # List MCP servers > Returns a paginated list of MCP servers in the caller's tenant. ## OpenAPI ````yaml /openapi.json get /api/svc/v1/mcp openapi: 3.1.0 info: title: TrueFoundry API description: API for TrueFoundry version: 0.1.0 contact: {} servers: - url: https://{controlPlaneURL} variables: controlPlaneURL: default: app.truefoundry.com description: Control Plane URL security: [] tags: - name: Agent - name: Agent Skills - name: Applications - name: Metrics - name: Apply - name: Artifacts - name: Audit Logs - name: Clusters - name: Jobs - name: Logs - name: MCP Servers V2 - name: MLRepos - name: Model Deployments - name: Models - name: Personal Access Tokens - name: Prompts - name: Provider Integrations - name: SCIM v2 - name: Secret Groups - name: Secrets - name: Teams - name: Traces - name: Users - name: Virtual Accounts - name: Role Bindings - name: Workspaces paths: /api/svc/v1/mcp: get: tags: - MCP Servers V2 summary: List MCP servers description: Returns a paginated list of MCP servers in the caller's tenant. operationId: MCPServerV2.listMCPServers parameters: - name: limit required: false in: query description: Number of items per page schema: minimum: 1 maximum: 1000 nullable: true default: 100 example: 10 type: integer - name: offset required: false in: query description: Number of items to skip schema: minimum: 0 nullable: true default: 0 example: 0 type: integer - name: filter required: false in: query description: >- JSON string: structured filter tree (AND/OR groups, column leaves on `name`, json_map leaves on `manifest` keys such as `type`). schema: nullable: true example: >- {"op":"AND","value":[{"column":"name","op":"eq","value":"my-server"}]} type: string - name: attributes required: false in: query description: >- Comma-separated list of attributes to return (e.g. `id,name`). When provided, only the specified fields are fetched. `id` is always included. schema: nullable: true example: id,name,manifest type: array items: type: string responses: '200': description: Paginated list of MCP servers in the caller's tenant. content: application/json: schema: $ref: '#/components/schemas/ListMCPServersResponseV2' security: - jwt: [] components: schemas: ListMCPServersResponseV2: type: object properties: data: description: Array of MCP servers matching the query. type: array items: $ref: '#/components/schemas/MCPServerV2' pagination: description: Pagination metadata. allOf: - $ref: '#/components/schemas/Pagination' required: - data - pagination title: ListMCPServersResponseV2 x-fern-type-name: ListMCPServersResponseV2 MCPServerV2: type: object properties: id: type: string description: Identifier for this MCP server. nullable: true fqn: type: string description: Fully qualified name. example: my-tenant:mcp-server:filesystem-tools tenantName: type: string description: Tenant the MCP server belongs to. manifest: oneOf: - $ref: '#/components/schemas/MCPServerManifest' description: >- User-supplied MCP server configuration. Sensitive fields inside `auth_data` (and other manifest secrets) are redacted for callers who do not have `MANAGE_MCP_SERVER` permission on this server. createdBySubject: description: >- Principal (user or service account) that originally created this MCP server. allOf: - $ref: '#/components/schemas/Subject' createdAt: format: date-time type: string description: MCP server creation timestamp. nullable: true updatedAt: format: date-time type: string description: MCP server last-update timestamp. nullable: true proxyUrl: type: string description: >- Proxy URL template for accessing the MCP server. Contains a `{{mcpProxyBaseURL}}` placeholder that callers must substitute with the actual gateway base URL before use. nullable: true isAuthOverrideSupported: type: boolean description: >- Whether the MCP server accepts per-subject auth overrides via `PUT /mcp/{mcpServerId}/auth`. nullable: true required: - fqn - tenantName - manifest - createdBySubject title: MCPServerV2 x-fern-type-name: MCPServerV2 Pagination: type: object properties: total: type: integer description: Total number of items example: 100 offset: type: integer description: Number of items skipped example: 0 nullable: true limit: type: integer description: Number of items per page example: 10 nullable: true required: - total title: Pagination x-fern-type-name: Pagination MCPServerManifest: type: object oneOf: - $ref: '#/components/schemas/RemoteMCPServerManifest' - $ref: '#/components/schemas/VirtualMCPServerManifest' - $ref: '#/components/schemas/OpenAPIMCPServerManifest' - $ref: '#/components/schemas/StdioMCPServerManifest' - $ref: '#/components/schemas/TfyManagedMCPServerManifest' title: MCPServerManifest x-fern-type-name: MCPServerManifest Subject: type: object properties: subjectId: type: string description: Subject ID subjectType: description: Subject type allOf: - $ref: '#/components/schemas/SubjectType' subjectSlug: type: string description: Subject slug nullable: true subjectDisplayName: type: string description: Subject display name nullable: true subjectPatName: type: string description: Subject PAT name nullable: true subjectControllerName: type: string nullable: true subjectExternalIdentitySlug: type: string description: External identity slug (external_identity_id:sub:email) nullable: true required: - subjectId - subjectType title: Subject x-fern-type-name: Subject RemoteMCPServerManifest: description: Connect to an external MCP Server endpoint. type: object required: - type - name - description - url - collaborators properties: type: description: +value=mcp-server/remote type: string enum: - mcp-server/remote name: description: The name of the MCP Server. type: string pattern: ^[a-z][a-z0-9\-]{1,71}[a-z0-9]$ description: description: Provide a brief description of the purpose of this MCP Server. type: string minLength: 1 maxLength: 1000 url: description: The endpoint URL for the MCP Server. type: string pattern: ^https?:\/\/[^\s]+$ tls_settings: $ref: '#/components/schemas/CustomTLSSettings' tool_settings: description: >- Customize tool descriptions or enable/disable specific tools from the MCP Server. type: array items: $ref: '#/components/schemas/MCPToolSetting' auth_data: $ref: '#/components/schemas/MCPServerAuth' collaborators: description: Users and Teams that have access to this MCP Server type: array items: $ref: '#/components/schemas/Collaborator' ownedBy: $ref: '#/components/schemas/OwnedBy' additional_headers: description: >- Additional HTTP headers sent on each request to the MCP server. If the same header is set in both `additional_headers` and `auth_data`, the `auth_data` value wins. type: object tags: description: >- Key-value pairs to categorize this MCP Server (e.g., by owner or environment). type: object title: RemoteMCPServerManifest x-fern-type-name: RemoteMCPServerManifest VirtualMCPServerManifest: description: TrueFoundry-hosted MCP Server composed of other MCP servers. type: object required: - type - name - description - servers - collaborators properties: type: description: +value=mcp-server/virtual type: string enum: - mcp-server/virtual name: description: The name of the Virtual MCP Server. type: string pattern: ^[a-z][a-z0-9\-]{1,71}[a-z0-9]$ description: description: >- Provide a brief description of the purpose of this Virtual MCP Server. type: string minLength: 1 maxLength: 1000 servers: description: List of source MCP servers to include in this virtual server. type: array items: $ref: '#/components/schemas/McpServerSource' collaborators: description: Users and Teams that have access to this Virtual MCP Server type: array items: $ref: '#/components/schemas/Collaborator' ownedBy: $ref: '#/components/schemas/OwnedBy' tags: description: >- Key-value pairs to categorize this Virtual MCP Server (e.g., by owner or environment). type: object title: VirtualMCPServerManifest x-fern-type-name: VirtualMCPServerManifest OpenAPIMCPServerManifest: description: Connect to an external OpenAPI Server endpoint. type: object required: - type - name - description - url - openapi_spec_source - collaborators properties: type: description: +value=mcp-server/openapi type: string enum: - mcp-server/openapi name: description: The name of the OpenAPI MCP Server. type: string pattern: ^[a-z][a-z0-9\-]{1,71}[a-z0-9]$ description: description: >- Provide a brief description of the purpose of this OpenAPI MCP Server. type: string minLength: 1 maxLength: 1000 url: description: >- The base URL where API requests will be sent. This should be the root endpoint of your API server, without any path suffix. type: string pattern: ^https?:\/\/[^\s]+$ openapi_spec_source: $ref: '#/components/schemas/OpenAPISpecSource' tls_settings: $ref: '#/components/schemas/CustomTLSSettings' enable_all_tools: description: >- When enabled, all tools from the OpenAPI spec will be available (up to 30 tools). Disable to select specific tools. type: boolean tool_settings: description: The tools to customize from the OpenAPI Server. type: array items: $ref: '#/components/schemas/OpenAPIMCPToolSetting' auth_data: $ref: '#/components/schemas/MCPServerAuth' collaborators: description: Users and Teams that have access to this OpenAPI Server type: array items: $ref: '#/components/schemas/Collaborator' ownedBy: $ref: '#/components/schemas/OwnedBy' additional_headers: description: >- Additional HTTP headers sent on each request to the upstream OpenAPI server. If the same header is set in both `additional_headers` and `auth_data`, the `auth_data` value wins. type: object tags: description: >- Key-value pairs to categorize this OpenAPI MCP Server (e.g., by owner or environment). type: object title: OpenAPIMCPServerManifest x-fern-type-name: OpenAPIMCPServerManifest StdioMCPServerManifest: description: Stdio MCP server configuration. type: object required: - name - description - collaborators - type - command properties: name: description: The name of the MCP Server. type: string pattern: ^[a-z][a-z0-9\-]{1,71}[a-z0-9]$ description: description: Provide a brief description of the purpose of this MCP Server. type: string minLength: 1 maxLength: 1000 collaborators: description: Users and Teams that have access to this MCP Server type: array items: $ref: '#/components/schemas/Collaborator' type: description: |- +value=mcp-server/stdio +sort=400 type: string enum: - mcp-server/stdio command: description: Executable to run for the stdio MCP server process. type: string minLength: 1 default: npx args: description: Arguments passed to the stdio MCP server command. type: array items: type: string tool_settings: description: >- Customize tool descriptions or enable/disable specific tools from the MCP Server. type: array items: $ref: '#/components/schemas/MCPToolSetting' auth_data: $ref: '#/components/schemas/MCPServerEnvAuth' ownedBy: $ref: '#/components/schemas/OwnedBy' tags: description: >- Key-value pairs to categorize this MCP Server (e.g., by owner or environment). type: object title: StdioMCPServerManifest x-fern-type-name: StdioMCPServerManifest TfyManagedMCPServerManifest: description: Connect to an external MCP Server endpoint. type: object required: - type - name - description - server_identifier - collaborators properties: type: description: +value=mcp-server/tfy-managed type: string enum: - mcp-server/tfy-managed name: description: The name of the MCP Server. type: string pattern: ^[a-z][a-z0-9\-]{1,71}[a-z0-9]$ description: description: Provide a brief description of the purpose of this MCP Server. type: string minLength: 1 maxLength: 1000 server_identifier: description: >- Catalog slug of the TrueFoundry-managed MCP server to connect to. Used to resolve the hosted endpoint and available tools. type: string pattern: ^[a-z][a-z0-9\-]{1,71}[a-z0-9]$ tool_settings: description: >- Customize tool descriptions or enable/disable specific tools from the MCP Server. type: array items: $ref: '#/components/schemas/MCPToolSetting' collaborators: description: Users and Teams that have access to this MCP Server type: array items: $ref: '#/components/schemas/Collaborator' ownedBy: $ref: '#/components/schemas/OwnedBy' auth_data: $ref: '#/components/schemas/TfyManagedMCPServerOAuth' tags: description: >- Key-value pairs to categorize this MCP Server (e.g., by owner or environment). type: object title: TfyManagedMCPServerManifest x-fern-type-name: TfyManagedMCPServerManifest SubjectType: type: string enum: - user - team - serviceaccount - virtualaccount - external-identity - agent-identity - role description: >- Type of the authenticated subject. "user" for human users, "serviceaccount" (also known as virtual account) for programmatic access. title: SubjectType x-fern-type-name: SubjectType CustomTLSSettings: description: >- Configure TLS settings for secure connections with custom CA certificates. type: object required: - reject_unauthorized properties: reject_unauthorized: description: >- When set to true, it will reject any connection which is not authorized with the list of supplied CAs. type: boolean default: true ca_cert: description: Add custom CA certificates to use for TLS verification. type: string title: CustomTLSSettings x-fern-type-name: CustomTLSSettings MCPToolSetting: description: MCP Tool Setting type: object required: - name properties: name: description: The unique name of the tool. type: string pattern: ^[A-Za-z0-9_.-]{1,128}$ description: description: >- Describe what this tool does. This helps AI models understand when to use it. type: string minLength: 1 maxLength: 20000 disabled: description: Allows to disable the tool. type: boolean annotations: $ref: '#/components/schemas/MCPToolAnnotations' title: MCPToolSetting x-fern-type-name: MCPToolSetting MCPServerAuth: type: object oneOf: - $ref: '#/components/schemas/MCPServerHeaderAuth' - $ref: '#/components/schemas/MCPServerOAuth2' - $ref: '#/components/schemas/MCPServerPassthrough' title: MCPServerAuth x-fern-type-name: MCPServerAuth Collaborator: type: object required: - subject - role_id properties: subject: description: 'Fully Qualified Name of the subject. eg: user:email or team:teamname' type: string role_id: description: Role ID for the resource type: string title: Collaborator x-fern-type-name: Collaborator OwnedBy: description: Names of the owners that own this resource type: object required: - account properties: account: description: The name of the account that owns this resource type: string title: OwnedBy x-fern-type-name: OwnedBy McpServerSource: description: MCP Server Source type: object required: - name properties: name: description: Name of the MCP server type: string enabled_tools: description: List of tools to enable from this source server. type: array items: type: string auth_data: $ref: '#/components/schemas/MCPServerHeaderOverrideAuth' title: McpServerSource x-fern-type-name: McpServerSource OpenAPISpecSource: type: object oneOf: - $ref: '#/components/schemas/RemoteSpecSource' - $ref: '#/components/schemas/UploadSpecSource' - $ref: '#/components/schemas/InlineSpecSource' title: OpenAPISpecSource x-fern-type-name: OpenAPISpecSource OpenAPIMCPToolSetting: description: OpenAPI MCP Tool Setting type: object required: - method - path - name - description properties: method: description: The HTTP method for this endpoint. type: string enum: - get - post - put - patch - delete - head path: description: The API endpoint path (e.g., /users/{id}). type: string name: description: The unique name of this tool, derived from OpenAPI operationId. type: string pattern: ^[A-Za-z0-9_.-]{1,128}$ description: description: >- Describe what this tool does. This helps AI models understand when to use it. type: string minLength: 1 maxLength: 20000 annotations: $ref: '#/components/schemas/MCPToolAnnotations' title: OpenAPIMCPToolSetting x-fern-type-name: OpenAPIMCPToolSetting MCPServerEnvAuth: description: >- Environment variable authentication for stdio MCP. For individual credentials, use a single {{placeholder}} name in values (same rules as header auth). type: object required: - type - env properties: type: description: +value=env type: string enum: - env env: description: >- Map each env variable to its value. For shared, enter the actual value. For individual, use a placeholder that will be filled in by each user (e.g. API_KEY {{API_KEY}}). type: object additionalProperties: type: string auth_level: description: >- Level at which this authentication will be applied. Values: global (default), per_user type: string enum: - global - per_user default: global title: MCPServerEnvAuth x-fern-type-name: MCPServerEnvAuth TfyManagedMCPServerOAuth: description: TfyManaged OAuth2 type: object required: - type - grant_type properties: type: description: OAuth2 authentication type: string enum: - oauth2 grant_type: description: The OAuth2 grant type to use for authentication. type: string enum: - authorization_code title: TfyManagedMCPServerOAuth x-fern-type-name: TfyManagedMCPServerOAuth MCPToolAnnotations: description: MCP Tool Annotations type: object properties: readOnlyHint: description: Indicates the tool only reads data and does not modify anything. type: boolean destructiveHint: description: Indicates the tool may perform destructive updates. type: boolean title: MCPToolAnnotations x-fern-type-name: MCPToolAnnotations MCPServerHeaderAuth: description: >- Authenticate using a static key or token sent as a request header. Choose shared vs individual credentials below. type: object required: - type - headers - auth_level properties: type: description: +value=header type: string enum: - header headers: description: >- Map each header name to its value. For shared, enter the actual value. For individual, use a placeholder that will be filled in by each user (e.g. Bearer {{API_KEY}}). type: object additionalProperties: type: string auth_level: description: >- Level at which this authentication will be applied. Values: global (default), per_user type: string enum: - global - per_user default: global title: MCPServerHeaderAuth x-fern-type-name: MCPServerHeaderAuth MCPServerOAuth2: description: OAuth2 type: object properties: type: description: OAuth2 authentication type: string enum: - oauth2 grant_type: description: The OAuth2 grant type to use for authentication. type: string enum: - authorization_code - client_credentials default: authorization_code authorization_url: description: URL for the authorization request type: string pattern: >- ^https:\/\/(([a-zA-Z0-9-]{1,63}\.)+[a-zA-Z]{2,63})(:[0-9]{1,5})?(\/[^\s]*)?$ token_url: description: The endpoint to exchange auth code for tokens. type: string pattern: >- ^https:\/\/(([a-zA-Z0-9-]{1,63}\.)+[a-zA-Z]{2,63})(:[0-9]{1,5})?(\/[^\s]*)?$ client_id: description: >- client ID for OAuth2 or the TrueFoundry secret FQN containing the client ID. type: string pattern: ^\S+$ client_secret: description: >- Client secret or the TrueFoundry secret FQN containing the client secret for OAuth2. type: string minLength: 1 registration_url: description: >- URL for dynamic client registration (RFC 7591). If provided, client credentials will be obtained automatically using the Dynamic Client Registration (DCR) process. type: string pattern: >- ^https:\/\/(([a-zA-Z0-9-]{1,63}\.)+[a-zA-Z]{2,63})(:[0-9]{1,5})?(\/[^\s]*)?$ introspection_url: description: >- URL to fetch token expiry (RFC 7662) when the provider does not return expires_in (e.g. Salesforce). Requires client_id and client_secret. type: string pattern: >- ^https:\/\/(([a-zA-Z0-9-]{1,63}\.)+[a-zA-Z]{2,63})(:[0-9]{1,5})?(\/[^\s]*)?$ provider: description: >- Select the OAuth provider when provider-specific configuration is required. type: string enum: - auth0 code_challenge_methods_supported: description: List of supported PKCE code challenge methods (S256 only) type: array items: type: string enum: - S256 jwt_source: description: Source of the JWT token to be used for verification. type: string enum: - access_token - id_token default: access_token scopes: description: List of scopes to request from the OAuth2 provider. type: array items: type: string minLength: 1 additional_token_params: description: >- Extra key/value pairs sent on every token endpoint request (e.g. Auth0 'audience'). type: object additionalProperties: type: string allOf: - $ref: '#/components/schemas/MCPServerOAuth2ProviderAuth0Settings' required: - type - grant_type - token_url - jwt_source title: MCPServerOAuth2 x-fern-type-name: MCPServerOAuth2 MCPServerPassthrough: description: >- Authenticate using your existing TrueFoundry account (PAT or Virtual Accounts). Your credentials are automatically passed to the MCP server. type: object required: - type properties: type: description: +value=passthrough type: string enum: - passthrough title: MCPServerPassthrough x-fern-type-name: MCPServerPassthrough MCPServerHeaderOverrideAuth: description: Override authentication for this source server type: object required: - type - headers properties: type: description: +value=header type: string enum: - header headers: type: object additionalProperties: type: string title: MCPServerHeaderOverrideAuth x-fern-type-name: MCPServerHeaderOverrideAuth RemoteSpecSource: description: Fetch the OpenAPI specification from a remote HTTP/HTTPS endpoint. type: object required: - type - url properties: type: description: +value=remote type: string enum: - remote url: description: URL to fetch the OpenAPI specification (JSON or YAML format). type: string pattern: ^https?:\/\/[^\s]+$ title: RemoteSpecSource x-fern-type-name: RemoteSpecSource UploadSpecSource: description: Fetch the stored/uploaded OpenAPI specification. type: object required: - type - url properties: type: description: +value=upload type: string enum: - upload url: description: >- Cloud storage path where the OpenAPI specification is stored (S3, GCS, or Azure Blob). type: string pattern: >- ^(s3://[^/]+|gs://[^/]+|https://[^.]+\.blob\.core\.windows\.net/[^/]+)/tfy-openapi-specs/(?:\d{4}-\d{2}/|[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+/)[a-f0-9-]+\.json$ title: UploadSpecSource x-fern-type-name: UploadSpecSource InlineSpecSource: description: >- Inline your OpenAPI specification directly. The spec will be stored securely. type: object required: - type - openapi_spec properties: type: description: +value=inline type: string enum: - inline openapi_spec: description: The OpenAPI specification as a JSON object or a JSON/YAML string. oneOf: - type: object - type: string title: InlineSpecSource x-fern-type-name: InlineSpecSource MCPServerOAuth2ProviderAuth0Settings: type: object properties: use_organization: description: >- When enabled, organization will be extracted from the inbound token and it will be included as the organization parameter on token endpoint requests. type: boolean default_organization: description: >- Fallback Auth0 organization when the inbound token does not include organization. type: string pattern: ^\S+$ title: MCPServerOAuth2ProviderAuth0Settings x-fern-type-name: MCPServerOAuth2ProviderAuth0Settings securitySchemes: jwt: type: http scheme: bearer bearerFormat: JWT ````