Update a connection’s instructions
PATCH /api/mcp-connections/{connectionId}/instructions
Sets the guidance the assistant reads before using this connection. Send null to clear it. 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
Guidance the assistant reads before it uses this connection’s tools. It also reads the connection’s records through it when it decides, writes and checks a reply. At most 8,192 bytes of UTF-8; a longer text is refused with 422 instructions_too_long. null clears it.
Example
Use this connection for order lookups. Ask the customer for the order number first.Responses
Section titled “ Responses ”The connection, as it now stands.
One connection with its endpoint, its discovered tools, and the governance set on each tool.
object
The MCP endpoint oHallo calls.
Example
https://mcp.example.com/mcpHow oHallo authenticates to the server. The credential itself is held in the secret store and is returned by no endpoint.
Guidance the assistant reads before it uses this connection’s tools. It also reads the connection’s records through it when it decides, writes and checks a reply.
The tools discovered on the server.
object
Example
get_orderThe tool’s JSON Schema for arguments.
object
The tool’s declared output schema, when it declares one.
object
Tool name to risk classification.
object
Tool name to the assurance a caller must reach, where one has been set. An absent entry takes the default for the tool’s risk classification.
object
Tool name to the governance in force on it: the risk classification, the assurance a caller must reach, the scope declaration and the last scope outcome. Resolved server-side, so what the API returns is what oHallo enforces.
object
The governance in force on one tool.
object
The tool’s risk classification; null when it has not been classified.
The assurance a caller must reach before the tool runs; null when the tool is unclassified.
The default assurance for the tool’s risk classification: read is anonymous; read_pii, write and write_pii are identified; destructive is high-assurance. Null when unclassified.
Where enforcedAssurance sits relative to default: the default itself, a setting raised above it, or a setting lowered below it. A lowered row is shown as Below default on the dashboard.
False when an agent does not call the tool: it has no risk classification, or no scope declaration. A tool with no declaration still reports the assurance it takes once declared.
A scope declaration. At record level a caller acts on the records their own conversation created: a tool that creates a record names the response field carrying its id in originates, and a tool that acts on one names the argument carrying that id in refArgs. oHallo checks every refArgs value before the call runs and the ownerField of every record the call returns.
object
The unit of ownership. record: the records the caller’s own conversation created. customer: a verified customer’s own records. account: the records of the company the verified customer’s record names. customer and account need a customer lookup on the connection (customer_lookup_missing, customer_tie_lookup_missing, account_lookup_missing).
Every argument carrying a record reference. Each is checked against the records the caller holds. Empty for a tool that only creates.
Example
[ "quote_id"]The argument that receives the caller’s bound reference, for a tool the server filters by it. Absent for a tool addressed by a record’s own id.
The response path naming the record’s owner, or the record itself at record level, as dotted field names. A field inside a list is named through the list with [], as in orders[].customer_id, and oHallo reads it on every element; a path holds at most one [], never as its last segment, and no numeric index. Required unless originates is set at record level.
Example
quote_idThe response path naming the id of a record this call creates. Refused on a read or read_pii tool, when the path echoes an argument of the same tool, and when it names a field inside a list.
Example
quote_idAt customer and account level: the names of fields a returned record uses for another party, such as a recipient, or at account level the customer who placed an order. Each is one of the default owner names (customer_id, account_id, client_id, owner_id, buyer_id, in any spelling), never the name ownerField ends in, and a field of the tool’s declared output schema when it has one. oHallo then does not read that field as an owner. Refused at record level.
Example
[ "buyer_id"]The assurance setting persisted for the tool, or null when none is set. enforcedAssurance is what oHallo applies: a setting equal to the default reports source: default, and a setting that breaks one of the two rules is not applied and the default is enforced in its place. On a tool declared at customer level a setting or default below identified is enforced at identified, and source is read against the default: raised on a read tool, whose default is anonymous, and default on every other class.
The last thing the scope check recorded on a tool, and when.
object
captured: a successful call returns the created record’s id at the originates path, and oHallo holds it for the conversation. originates_missing: a successful call returns no id at the originates path. originates_refused: oHallo does not hold the id at the originates path of a successful call: the tool is classified read or read_pii, or the path runs through the field designated on the connection as the eID reference or the national identity number, whether or not an id is returned; or the result carries more than one id there, the id repeats one of the call’s arguments, another conversation on the connection already holds it, the sender is not proven, the call has no conversation or caller to hold it for, or the conversation’s held records expire as it is written. set_write_failed: a successful call returns an id at the originates path, and the write that holds it for the conversation fails. owner_absent: at record level, on a tool declared with an ownerField, no part of a result names an owner there and no created-record outcome applies, and the result is returned. At customer and account level, a result, or any part of it, names no owner at ownerField that can be checked, and no record in its text content or structured content names another party: a record or list element without one, a list element that is not a record, a JSON scalar, text that is not JSON, an item that is not text, a field beside the content, a missing list, a result with no content, or a declaration with no ownerField; the result is withheld. An empty list passes at those levels and records nothing. mismatch: a record in the result’s text content or structured content names a record or party the caller does not hold, and the result is withheld: at record level a value under the ownerField name or a refArgs name that is not a record the conversation created; at customer level anyone but the verified customer at ownerField, or anyone but that customer or their company under the ownerField name or a default owner name; at account level anyone but their company at ownerField or under either name; otherPartyFields excepted. A JSON number that is not a whole number from 0 to 9007199254740991 under any of these names counts as another party. A result with a record in its text content or structured content that names another party, and also a part with no owner, records mismatch. A withheld result records owner_absent or mismatch in place of any created-record outcome.
True when the tool’s stored factor requirement asks for a factor category or type, or a number of factors, that no verification method gives. No caller reaches such a tool at any level, and the dashboard shows it as needing a method.
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, or instructions is over 8,192 bytes of UTF-8 (error: "instructions_too_long").
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"]