Assign a connection’s tools to agents
PUT /api/mcp-connections/{connectionId}/assignments
Gives named agents the tools they may call on this connection. A tool is called only by an agent it is assigned to, so this is the step that puts a connection to work. Each entry replaces that agent’s allowed set for this connection. An empty list is not a revocation: it places no restriction and exposes every tool, so remove an agent’s access with DELETE /api/agent-definitions/{agentId}/mcp-connections/{connectionId}. Requires the mcp:write and agents:write scopes. Each agent named is one created in the account, and each tool one the connection declares, whoever calls. Assigning tools changes the agent, so a key restricted to a brand or workspace assigns them only to an agent whose every MCP connection is inside its restriction, the rule PATCH /api/agent-definitions/custom/{id} applies.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The unique identifier of the MCP connection.
Request Body required
Section titled “Request Body required ”object
object
From GET /api/agent-definitions.
Example
d4e5f6a7-8901-4abc-8ef0-1234567890abTool names this agent may call. An empty list places NO restriction and exposes every tool on the connection; to remove an agent’s access use DELETE /api/agent-definitions/{agentId}/mcp-connections/{connectionId}.
Example
[ "get_order"]Responses
Section titled “ Responses ”The assignments were written.
Simple success acknowledgment returned by action endpoints (reply, resolve, take-over, etc.).
object
Always true on success.
Example
trueThe caller may not change this connection or an agent it names. 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. For such a key, an agent that uses an MCP connection outside its restriction also answers code: "key_lock". An agent provided by oHallo answers code: "platform_agent", whoever calls. Agent assignments on a system connection are the account’s and stay open.
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]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.
Example
11223344-5566-4788-99aa-bbccddeeff00On 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.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]No such connection, or it is outside the API key’s brand or workspace restriction. A connection the key cannot reach is not disclosed. An agent the account does not have answers 404 as well, whoever calls.
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]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.
Example
11223344-5566-4788-99aa-bbccddeeff00On 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.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]Validation error, a tool the connection does not declare (undeclaredTools names those tools and declaredTools the connection’s own), or the Identity Verification connection, which is assigned to no agent (connectionId names it); nothing is written.
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]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.
Example
11223344-5566-4788-99aa-bbccddeeff00On 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.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]