List MCP connections

GET

/api/mcp-connections

Production

Lists the MCP connections within the caller’s reach. An API key restricted to a brand or workspace sees the connections of that brand or workspace; an account-wide connection is seen by an unrestricted key only. Pass scope=tenant-built to leave out oHallo’s own system connections. Requires the mcp:read scope.

Authorizations

bearerAuth

Parameters

Query Parameters

scope

string

Allowed values: tenant-built

Set to ‘tenant-built’ to leave out oHallo’s own system connections.

Responses

200

The connections.

Array<object>

A registered MCP server: one business system the assistant can call tools on.

object

connectionId

required

string format: uuid

name

required

Operator-facing name.

string

Example

Example Company orders

connectionType

required

‘custom’ is a server the account built and hosts. ‘system’ is oHallo’s own tooling, configured by oHallo; an API key sets its guardrails, per-tool assurance and agent assignments.

string

Allowed values: system marketplace custom paid

capabilities

required

Capability labels declared for the connection.

Array<string>

scope

required

Where the connection applies: the whole account, one brand, or one workspace.

string

Allowed values: tenant brand workspace

brandId

The brand the connection is scoped to, if any.

string | null format: uuid

workspaceId

The workspace the connection is scoped to, if any.

string | null format: uuid

status

required

The last health result. A failing connection stays visible rather than disappearing.

string

Allowed values: active degraded error unreachable

templateId

The catalogue connector this was installed from, if any.

string | null

toolCount

How many tools the last discovery found.

integer

403

The API key does not carry the mcp:read scope.

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"
]