Deprecation of MCP Servers APIs

Applicable to: Users and automation that call the TrueFoundry control-plane MCP Server APIs directly - for example GitOps pipelines, custom integrations, or scripts that create, update, list, or delete MCP servers or manage per-subject auth overrides. If you only use the TrueFoundry UI or IDE MCP connection flows, no action is required.

What Is Changing

The legacy /v1/mcp-servers and /v1/mcp-user-auth control-plane APIs are deprecated. They are replaced by the consolidated /v1/mcp APIs - see the MCP Servers API reference for endpoint documentation. Existing integrations will continue to work during the transition period. No changes are required immediately, but we strongly encourage migrating to the new endpoints before the removal date.

API Migration Reference

MCP server CRUD

Operation	Deprecated	Replacement
List servers	`GET /v1/mcp-servers`	`GET /v1/mcp`
Get server	`GET /v1/mcp-servers/{mcpServerId}`	`GET /v1/mcp/{mcpServerId}`
Create or update	`PUT /v1/mcp-servers`	`PUT /v1/mcp`
Delete server	`DELETE /v1/mcp-servers/{mcpServerId}`	`DELETE /v1/mcp/{mcpServerId}`
Get by name	`GET /v1/mcp-servers/name/{name}`	Use `GET /v1/mcp` with a name filter, then operate on the returned `id`
Delete by name	`DELETE /v1/mcp-servers/name/{name}`	Use `GET /v1/mcp` with a name filter, then `DELETE /v1/mcp/{mcpServerId}`

List and get responses: GET /v1/mcp and GET /v1/mcp/{mcpServerId} no longer include authStatus. To check whether a subject is authenticated, call GET /v1/mcp/{mcpServerId}/auth/state with subjectId and subjectType instead. When authentication is still required, the response returns a reason field instead of the legacy message field. Create or update: PUT /v1/mcp replaces PUT /v1/mcp-servers. Pass manifest, dryRun, and force:

{
  "manifest": {....},
  "dryRun": false,
  "force": false
}

If the server returns 417 because outbound auth changes would delete existing per-subject auth records, retry the same PUT /v1/mcp request with force set to true. When true, force acknowledges that updating the manifest will delete existing per-subject auth records.

Per-subject auth

Operation	Deprecated	Replacement	Request body
Get auth	`GET /v1/mcp-servers/{mcpServerId}/auth`	`GET /v1/mcp/{mcpServerId}/auth`	API reference
Delete auth	`DELETE /v1/mcp-servers/{mcpServerId}/auth`	`DELETE /v1/mcp/{mcpServerId}/auth`	API reference
List auth overrides	`GET /v1/mcp-user-auth/{mcpServerId}`	`GET /v1/mcp/{mcpServerId}/auth`	API reference
Set auth override	`PUT /v1/mcp-user-auth/{mcpServerId}`	`PUT /v1/mcp/{mcpServerId}/auth`	API reference
Delete auth override	`DELETE /v1/mcp-user-auth/{mcpServerId}`	`DELETE /v1/mcp/{mcpServerId}/auth`	API reference

Timeline

Milestone	Date
Deprecation announcement	1st July, 2026
Legacy `/v1/mcp-servers` and `/v1/mcp-user-auth` APIs fully removed	30th September, 2026

We strongly encourage migrating to the /v1/mcp APIs well ahead of 30th September, 2026 to avoid disruptions to MCP server management and auth override workflows.

If you have questions or need help migrating your integrations, reach out to support@truefoundry.com - we’re happy to assist.

​What Is Changing

​API Migration Reference

​MCP server CRUD

​Per-subject auth

​Timeline

What Is Changing

API Migration Reference

MCP server CRUD

Per-subject auth

Timeline