Skip to main content
POST
Performs the same validation as the Test Connection button in the dashboard’s MCP Servers section: it opens the transport, runs the MCP initialize handshake, and lists the server’s tools. Nothing is created or stored — use it to verify a configuration before assigning it to an agent.
A failed connection is a normal result, not an error: the response is 200 with success: false and a message. Only a malformed request returns 400.

Request Body

string
required
MCP server endpoint URL.Example: https://mcp.example.com/sse
string
default:"sse"
Transport protocol.Supported values:
  • sse — Server-Sent Events
  • http — Streamable HTTP
object | array
Authentication headers. Accepts either an object ({ "Authorization": "Bearer ..." }) or an array of key/value pairs ([{ "key": "Authorization", "value": "Bearer ..." }]).
object
Optional MCP initialization options. Accepted and stored for parity with the dashboard; not currently exercised during the handshake.

How It Works

  1. Validates the request body (url is required and must be a valid URL).
  2. Opens the transport — SSE or Streamable HTTP — using any auth_headers provided.
  3. Runs the MCP initialize handshake and calls listTools.
  4. Returns the connection status, tool count, and the tool list (name + description).
To make a tested connection show as Connected on an agent, simply create or update the agent with the MCP server — the API automatically re-tests each MCP server on save. See Create Agent.

Troubleshooting