Skip to main content
POST
Probe an MCP server

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

tenant
string
required

Tenant whose MCP servers you are managing. Get it from the backoffice GET /auth/v1/me/claudia-projects, which answers with the tenant your credentials cover. A tenant your credentials do not cover is indistinguishable from one that does not exist.

Body

application/json

The MCP server to probe. Nothing is stored — the probe only reports whether the server answers.

url
string
required

The MCP endpoint to call, http or https. Probed exactly as written, with the same request the agent runtime makes, so a passing probe means the runtime will reach the same endpoint.

Example:

"https://mcp.acme.com/mcp"

authType
enum<string>
required

How to authenticate the probe. forwarded_user and oauth are probed without any credential, because their identity only exists at agent call time — such a server may legitimately answer valid: false and still be worth saving.

Available options:
none,
bearer,
apiKey,
forwarded_user,
oauth
Example:

"bearer"

credentials
string

The secret to probe with, in full. Omit it together with serverId to re-probe an already registered server using its stored secret.

Example:

"sk-live-9f3c2b7a"

customHeaders
object

Extra headers to send on the probe. Always taken from this request, so a headers-only change can be probed before it is saved.

Example:
serverId
string

An already registered server to reuse the stored secret from, as returned by listMcpServers. The stored secret is reused only while url and authType still match what is stored for it; change either and the probe runs with no credential, so you must supply one to get a truthful answer.

Example:

"6683f1c2a4b19e0012ab34cd"

Response

The probe ran. Read valid — a server that is down answers here, not as a failed request.

What the probe found. A server that is down or misbehaving is reported here as valid: false, not as a failed request.

valid
boolean
required

Whether the server answered the tool listing successfully.

Example:

true

toolsCount
integer<int32>

How many tools the server exposed. Absent when the probe did not succeed.

Example:

7

reason
enum<string>

Why the probe failed. UNREACHABLE is network or timeout, AUTH_FAILED means the credential was rejected, RPC_ERROR means the server answered with an error, INVALID_RESPONSE means it answered something that is not MCP. Absent when valid.

Available options:
UNREACHABLE,
RPC_ERROR,
INVALID_RESPONSE,
AUTH_FAILED
Example:

"UNREACHABLE"

error
string

A short description of the failure. Absent when valid.

Example:

"Could not reach the MCP server"