Skip to main content
POST
Test an MCP server connection and list its tools

Authorizations

Authorization
string
header
required

A Recursion API key, created in the console under API keys.

Headers

x-tenant-id
string

Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.

Minimum string length: 1
x-organization-id
string

Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or default.

Minimum string length: 1

Body

application/json

Request body for a live connection test against an MCP server, running the same credential resolution a session would. An unreachable server is reported in the response body, not as an HTTP error.

server_url
string
required

The MCP server to connect to. Must be http or https and must not embed credentials.

vault_ids
string[]

Vaults whose credentials may be used, scoped exactly as a session's grant is. Omit to probe unauthenticated.

Response

Response body of POST /managed-agents/v1/mcp/probe: the result of one live connection attempt to an MCP server, run through the same URL and vault resolution a real session uses. This envelope is a verdict rather than a resource: a server that is down is still HTTP 200 with ok=false, so a caller can distinguish "the server you configured is unreachable" from "this API is unreachable". Nothing is persisted by a probe.

Response body of POST /managed-agents/v1/mcp/probe: the result of one live connection attempt to an MCP server, run through the same URL and vault resolution a real session uses. This envelope is a verdict rather than a resource: a server that is down is still HTTP 200 with ok=false, so a caller can distinguish "the server you configured is unreachable" from "this API is unreachable". Nothing is persisted by a probe.

credential_matched
boolean
required

True when a credential from the named vaults was opened and attached to the request. It reports whether this attempt was authenticated, not whether a credential exists: a credential that matched the server URL but could not be opened reports false and sets credential_unopenable, because nothing was sent.

deployment_authorized
boolean
required

Deprecated. Always false: deployment-wide hosted MCP reader policies are disabled. Use a vault credential or organization-scoped integration grant for authenticated tool calls.

ok
boolean
required

True when the server completed the handshake and returned a tool list.

reachable
boolean
required

True when the server answered. Either the handshake succeeded (protocol_version is set), even if listing tools then failed, or the server refused the credential or its absence with HTTP 401 or 403 (protocol_version is absent): the URL and network are fine, and the credential is what to fix.

tools
object[]
required

Tools the server advertised on this attempt. Always an array and never null: empty means the handshake succeeded but the server offered no tools, or listing them failed, which is what ok=false plus reachable=true reports.

credential_unopenable
enum<string>

Set when a credential matched this server URL and could not be opened, so the request carried no auth header. external_reference means the material is held outside this service and must be re-entered here; material_missing means the credential row carries no stored value. Empty when none matched or the match was usable.

Available options:
external_reference,
material_missing
error
string

Operator-facing diagnostic when the probe failed. Never contains credential material.

fault
enum<string>

Set when the server was never reached for a reason other than the network, with reachable=false. egress_blocked means the server URL resolves to a private, loopback, link-local, or metadata address, which this service refuses to connect to; use a public URL. token_invalid means the stored token contains a line break, so it cannot be sent as a header; save it again without it. Empty for every other outcome, including genuine network failures.

Available options:
egress_blocked,
token_invalid
protocol_version
string

The MCP protocol version used.

server_name
string

What the server called itself during the handshake, which is how an operator confirms the URL reached the intended service.