Add a guardrail
POST /api/mcp-connections/{connectionId}/guardrails
Adds one rule on one tool. condition is an expression over the call’s arguments; when it is present the rule applies only to calls that match. An escalate condition is graded after the call returns, against the arguments and the result. Requires the mcp:write scope.
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
Example
create_orderExample
approval_gateAn expression over the call’s arguments, named as args.<name>. An escalate condition can also name the tool’s result, whose data is at result.structuredContent.<field>. Omit to apply the rule to every call of the tool.
Example
args.amount > 1000Settings for the rule, such as maskFields for a mask.
object
Defaults to true.
Responses
Section titled “ Responses ”The guardrail was created.
One rule oHallo applies to the calls of a tool. A deny, approval_gate or mask rule is evaluated before the call runs; an escalate rule is graded after the call returns.
object
Example
create_order‘approval_gate’ holds the call for a person, ‘deny’ refuses the call, ‘mask’ removes fields from the result, and ‘escalate’ lets the call run: when its condition matches a successful answer, the agent that called the tool receives an escalation_signal with the answer.
The rule’s settings. condition is an expression over the call’s arguments, named as args.<name>; an escalate condition is graded after the call and can also name the tool’s result, whose data is at result.structuredContent.<field>. maskFields lists the fields a mask removes. On an escalate rule, escalationType and description become the type and description of the escalation_signal.
object
The caller may not change this connection. People need the owner or admin role. An API key needs the mcp:write scope; a key restricted to a brand or workspace receives code: "key_lock" for an action its restriction does not cover, and for a change to what oHallo configures on a system connection (its instructions, its tools’ risk classifications, or a version restore). Guardrails, per-tool assurance and 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.
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, including a condition expression that does not compile.
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"]