---
title: "Prepare removing an organization connection"
method: POST
path: "/v1/mcp-connections/{connectionId}/removal-request"
tags: ["Capability Sources"]
---

# Prepare removing an organization connection

`POST /v1/mcp-connections/{connectionId}/removal-request`

## Request

- Base URL: `https://api.openworklabs.com`
- URL: `https://api.openworklabs.com/v1/mcp-connections/{connectionId}/removal-request`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Prepares removing one organization connection (connector) from OpenWork and returns a link where the person confirms it. Nothing is removed by this call: the connection, who can use it, its stored accounts and OAuth app are deleted only when the person opens the link and confirms in OpenWork. It never deletes anything in the connected service. Only when the user explicitly asks to remove a connection: first list connections with getMcpConnections and pick the one whose name matches; if several could match, ask the user which one and do not guess. Send its exact name as expectedName. A connection that plugins need is refused unless detachFromPlugins is true, which you may send only after telling the user which plugins use it and they agree. Needs the Remove any connection permission, or having added the connection. Give the person handoff.url and handoff.instructions; afterwards, list connections with getMcpConnections to confirm it is gone.

## Path parameters

- `connectionId` string, typeid, required

## Request body

- ExternalMcpConnectionRemovalRequestBody
  - `expectedName` string, required: The connection's exact name, as getMcpConnections lists it. Nothing is prepared when it does not match.
  - `detachFromPlugins` boolean: The user agreed it may be removed from plugins that need it. Send true only after telling the user which plugins use it.

## Response `200`

The removal is ready for the person to confirm in OpenWork.

- ExternalMcpConnectionRemovalRequestResponse
  - `status` 'confirmation_required', required
  - `connection` object, required
    - `id` string, required
    - `name` string, required
    - `url` string, required
  - `requiredBy` ExternalMcpConnectionRequiredBy[], required
    - `pluginId` string, required
    - `name` string, required
  - `handoff` object, required
    - `action` 'open_link', required
    - `url` string, required
    - `instructions` string, required

## Other responses

- `400`: Invalid request.
- `401`: The caller must be signed in.
- `403`: The caller may not remove this connection.
- `404`: Unknown connection, or removing connections through agents is off for this organization.
- `409`: The name does not match this connection, or plugins need it.

## Changes

- **2026-10-21** `8b797799efc8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/openworklabs/apis/den-api/changes/v1/mcp-connections/:connectionId/removal-request/post.md)

---

[API](https://skmtc.dev/openworklabs/apis/den-api.md) · [All operations](https://skmtc.dev/openworklabs/apis/den-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openworklabs/apis/den-api/revisions/6b535fe28240?raw)