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.

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 /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 /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

True when a deployment-owned access-token policy authorizes this endpoint for the organization and each request mints a token for the deployment's reader identity. Distinct from credential_matched: no vault credential is involved. For endpoints that answer discovery unauthenticated (Google hosted MCPs), a green tool list proves connectivity and discovery, not provider-side IAM — only a real tool call does.

ok
boolean
required

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

reachable
boolean
required

True when the handshake succeeded, even if listing tools then failed.

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.

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.