Test MCP Connection | SpeechifyAI API

Probe a customer-supplied MCP server config without persisting anything. The server opens the configured transport, runs the initialize + list_tools handshake, and returns either the discovered tool catalogue or a structured error string. Pass tool_id from the edit-form flow when the auth payload carries _set markers but no plaintext, so the server can hydrate the stored secret from the encrypted column before probing.

Probe a customer-supplied MCP server config without persisting anything. The server opens the configured transport, runs the `initialize` + `list_tools` handshake, and returns either the discovered tool catalogue or a structured error string. Pass `tool_id` from the edit-form flow when the auth payload carries `_set` markers but no plaintext, so the server can hydrate the stored secret from the encrypted column before probing.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Request

This endpoint expects an object.

configobjectRequired

Config shape for kind=mcp. The worker opens the configured transport at session start, runs initialize + list_tools, and registers each discovered remote tool as a livekit-agents function_tool proxying through the long-lived ClientSession.

Response headers

X-Request-IDstring

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an X-Request-ID request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an `X-Request-ID` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope.

Response

Probe result. The 200 envelope is used for both success and structured failure — inspect error to disambiguate. Network and validation failures never bubble up as non-2xx so a client can render them inline next to the form.

toolslist of objects or null

errorstring

detailsobject

Structured upstream signal for an MCP probe failure. All fields are optional; a client renders what’s present. stage names the phase the probe was in (validation, oauth2_token, mcp_connect, mcp_initialize, mcp_notify, mcp_list_tools). oauth2_error / oauth2_error_description mirror RFC 6749 §5.2 when the customer’s auth server returned the standard error shape. http_status is the upstream status code for transport failures. upstream_body is a truncated prefix (max ~1 KiB) of the upstream response body when the failure isn’t structured. field_hint names a form field (endpoint, transport, token, token_url, client_id, client_secret, scope) a client should highlight so the customer knows what to fix.

Errors

400

Bad Request Error

401

Unauthorized Error

$	curl -X POST https://api.speechify.ai/v1/agents/tool-definitions/test-mcp-connection \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"config": {
>	"endpoint": "https://example.com/webhook",
>	"auth": {
>	"type": "none"
>	},
>	"transport": "http_streamable"
>	}
>	}'

1	{
2	"tools": [
3	{
4	"name": "Example name",
5	"description": "Example description."
6	}
7	],
8	"error": "example",
9	"details": {
10	"stage": "validation",
11	"http_status": 1,
12	"oauth2_error": "example",
13	"oauth2_error_description": "example",
14	"upstream_body": "example",
15	"field_hint": "example"
16	}
17	}

Authentication

Headers

Request

Response headers

Response

Errors