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} |
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
}
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.
