---
title: "Remove an MCP server"
method: DELETE
path: "/api/v1/org-mcp-servers/{server_id}"
tags: ["authed"]
---

# Remove an MCP server

`DELETE /api/v1/org-mcp-servers/{server_id}`

## Request

- Base URL: `https://api.teaflask.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.teaflask.com/api/v1/org-mcp-servers/{server_id}`
- Auth: none declared

Removes a server: agents lose its tools and its credential is
discarded. While published agents use its tools, removing needs confirm.

## Path parameters

- `server_id` string, uuid, required: The server's id, as list_org_mcp_servers returns it.

## Query parameters

- `confirm` boolean: Set true only after the person you're acting for has agreed to go ahead, having been told which published agents use this server's tools; a call without it names those agents and removes nothing.

## Response `200`

Successful Response

- OrgMcpServerResponse
  - `id` string, uuid, required: The server's id.
  - `handle` string, required: The server's short name in agent tool names; it never changes.
  - `display_name` string, required: The server's name in the dashboard.
  - `host` string, required: The host name of the server's address.
  - `state` 'active' | 'needs_reconnect' | 'failed', required
  - `last_error` string, nullable, required: Why the server last failed to connect, or null.
  - `sign_in` 'oauth' | 'token' | 'none', required
  - `signed_in_by` OrgMcpServerSignedInBy, required
    - `id` string, uuid, required: The person's id.
    - `name` string, required: The person's name, or their email without one.
  - `header_names` string[], required: The names of the headers carrying its access token.
  - `tool_count` integer, required: How many tools the server lists now.
  - `new_tool_count` integer, required: How many of those arrived after the server was added.
  - `skipped_tools` OrgMcpServerSkippedTool[], required: Tools the server lists that agents can't use, and why.
    - `name` string, required: The tool's name on the server.
    - `reason` string, required: Why agents can't use this tool.
  - `first_listed_at` string, date-time, required: When the server was added.
  - `tools_refreshed_at` string, date-time, required: When its tool list was last read.
  - `removed_at` string, date-time, nullable, required: When the server was removed, or null while it is live.
  - `created_at` string, date-time, required: When the server was created.
  - `version` integer, required: Pass back as expected_version when renaming the server.

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: The server is gone
- `405`: Method not allowed
- `409`: Published agents use this server's tools and the removal was not confirmed
- `422`: Validation error
- `500`: Internal server error

## Changes

- **2026-11-03** `c6ac9fd6657f`: 7 info
  - removed the `STEEP_LEARNING_DISABLED` enum value from the `error/code` response property for the response status `401`
  - removed the `STEEP_LEARNING_DISABLED` enum value from the `error/code` response property for the response status `403`
  - removed the `STEEP_LEARNING_DISABLED` enum value from the `error/code` response property for the response status `404`
  - removed the `STEEP_LEARNING_DISABLED` enum value from the `error/code` response property for the response status `405`
  - …3 more

[Operation history](https://skmtc.dev/teaflask/apis/teaflask-api/changes/api/v1/org-mcp-servers/:server_id/delete.md)

---

[API](https://skmtc.dev/teaflask/apis/teaflask-api.md) - [All operations](https://skmtc.dev/teaflask/apis/teaflask-api/llms.txt) - [OpenAPI document](https://skmtc.dev/teaflask/apis/teaflask-api/revisions/c6ac9fd6657f?raw)