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

# Deprecation of MCP Servers APIs

> The /v1/mcp-servers and /v1/mcp-user-auth control-plane APIs are deprecated in favour of /v1/mcp. Existing integrations continue to work during the transition period.

<Warning>
  **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.
</Warning>

## 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](/docs/api-reference/mcp-servers-v2) 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`:

```json theme={"dark"}
{
  "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](/docs/api-reference/mcp-servers-v2/list-mcp-user-auth-overrides)            |
| Delete auth          | `DELETE /v1/mcp-servers/{mcpServerId}/auth` | `DELETE /v1/mcp/{mcpServerId}/auth` | [API reference](/docs/api-reference/mcp-servers-v2/disconnect-a-subject-from-an-mcp-server) |
| List auth overrides  | `GET /v1/mcp-user-auth/{mcpServerId}`       | `GET /v1/mcp/{mcpServerId}/auth`    | [API reference](/docs/api-reference/mcp-servers-v2/list-mcp-user-auth-overrides)            |
| Set auth override    | `PUT /v1/mcp-user-auth/{mcpServerId}`       | `PUT /v1/mcp/{mcpServerId}/auth`    | [API reference](/docs/api-reference/mcp-servers-v2/set-a-per-subject-auth-override)         |
| Delete auth override | `DELETE /v1/mcp-user-auth/{mcpServerId}`    | `DELETE /v1/mcp/{mcpServerId}/auth` | [API reference](/docs/api-reference/mcp-servers-v2/disconnect-a-subject-from-an-mcp-server) |

## Timeline

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

<Warning>
  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.
</Warning>

***

If you have questions or need help migrating your integrations, reach out to [**support@truefoundry.com**](mailto:support@truefoundry.com) - we're happy to assist.