Register an MCP connection
POST /api/mcp-connections
Registers an MCP server and discovers its tools: oHallo stores the credential, calls tools/list on the endpoint, and creates the connection only if that succeeds. The tools are not in use yet; assign them to an agent with PUT /api/mcp-connections/{connectionId}/assignments. Requires the mcp:write scope, and a key restriction that covers the brand or workspace the connection is scoped to.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”Registers an MCP server. The body carries the credential oHallo will present to that server: it is written to the secret store before the connection is created, and no endpoint returns it. Send the request over HTTPS and keep the value out of shell history and source control.
object
Operator-facing name.
Example
Example Company ordersThe MCP endpoint, a public https address. An http address, an address on a private network or on a port other than 443 or 80 is refused with 400.
Example
https://mcp.example.com/mcpHow oHallo authenticates to the server. Defaults to ‘none’.
Defaults to ‘custom’.
Capability labels for the connection.
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.
Scope the connection to one brand. Omit both this and workspaceId for an account-wide connection.
Scope the connection to one workspace.
AuthType ‘api_key’, bearer form: the token oHallo sends as Authorization: Bearer.
AuthType ‘api_key’, named-header form: each entry is a header the server authenticates by. Use this instead of apiKey when the server expects its own header names.
object
AuthType ‘oauth2_client’: where oHallo requests a token, a public https address.
AuthType ‘oauth2_client’.
AuthType ‘oauth2_client’.
Responses
Section titled “ Responses ”The connection was created.
object
The endpoint is not a public https address, authType is one a custom server does not use (the message names the ones it does), or a field the chosen authType needs is missing. The message names what to fix.
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"]The caller may not register a connection here. People need the owner or admin role. An API key needs the mcp:write scope; a restricted key receives code: "key_lock" when it registers outside its restriction, which includes an account-wide connection.
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"]The brand or workspace named is not this account’s, or is outside the key’s restriction.
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"]The endpoint could not be reached, rejected the credential, or reported no tools; detail carries what the endpoint said. Or instructions is over 8,192 bytes of UTF-8 (error: "instructions_too_long"). Nothing is stored.
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"]