Remove an agent's access to a connection

DELETE

/api/agent-definitions/{agentId}/mcp-connections/{connectionId}

• Production

Detaches an agent from an MCP connection, so it may call none of its tools. This is how access is removed: an empty allowedTools on PUT /api/mcp-connections/{connectionId}/assignments places no restriction and exposes every tool instead. The agent is one created in the account, whoever calls. Requires the mcp:write and agents:write scopes, and a key restriction that reaches the connection.

Authorizations

• bearerAuth

Parameters

Path Parameters

agentId

required

string format: uuid

The unique identifier of the agent.

connectionId

required

string format: uuid

The unique identifier of the MCP connection.

Responses

204

The agent no longer reaches this connection. Detaching an agent that was not attached is not an error.

403

The caller may not change this connection. People need the owner or admin role. An API key needs the mcp:write and agents:write scopes; a key restricted to a brand or workspace receives code: "key_lock" for an action its restriction does not cover. An agent provided by oHallo answers code: "platform_agent".

Standard error response returned by all endpoints on failure.

object

error

required

A human-readable error message describing what went wrong.

string

Example

Conversation not found

code

A machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.

string

Example

key_lock

missing_scopes

On a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.

Array<string>

Example

[
  "mcp:write"
]

entryId

On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.

string format: uuid

Example

11223344-5566-4788-99aa-bbccddeeff00

connectionId

On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.

string

undeclaredTools

On the same 422: the tool names the connection does not declare.

Array<string>

Example

[
  "get_orders"
]

declaredTools

On the same 422: the tools the connection declares.

Array<string>

Example

[
  "get_order",
  "search_orders"
]

404

No such connection, or it is outside the API key’s brand or workspace restriction. An agent the account does not have answers 404 as well, and so does an agent id that is not a UUID, with nothing detached.

Standard error response returned by all endpoints on failure.

object

error

required

A human-readable error message describing what went wrong.

string

Example

Conversation not found

code

A machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.

string

Example

key_lock

missing_scopes

On a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.

Array<string>

Example

[
  "mcp:write"
]

entryId

On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.

string format: uuid

Example

11223344-5566-4788-99aa-bbccddeeff00

connectionId

On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.

string

undeclaredTools

On the same 422: the tool names the connection does not declare.

Array<string>

Example

[
  "get_orders"
]

declaredTools

On the same 422: the tools the connection declares.

Array<string>

Example

[
  "get_order",
  "search_orders"
]