Test an MCP connection

POST

/api/mcp-connections/{connectionId}/test

• Production

Calls the endpoint again with the stored credential and records the result as the connection’s status. Use it after changing the server or its credential. It takes the mcp:write scope rather than mcp:read: it makes oHallo open an outbound connection and it rewrites stored state.

Authorizations

• bearerAuth

Parameters

Path Parameters

connectionId

required

string format: uuid

The unique identifier of the MCP connection.

Responses

200

The probe ran. status is the result it recorded; skipped is true for a system connection, which is not probed.

object

status

required

string

Allowed values: active degraded error

consecutiveFailures

integer

changed

The stored status moved.

boolean

skipped

boolean

403

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

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

404

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

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