> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telzino.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Test MCP Connection

> Validate an MCP server configuration and list its tools, without assigning it to an agent

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.

<Info>
  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`.
</Info>

## Request Body

<ParamField body="url" type="string" required>
  MCP server endpoint URL.

  **Example:** `https://mcp.example.com/sse`
</ParamField>

<ParamField body="transport_type" type="string" default="sse">
  Transport protocol.

  **Supported values:**

  * `sse` — Server-Sent Events
  * `http` — Streamable HTTP
</ParamField>

<ParamField body="auth_headers" type="object | array">
  Authentication headers. Accepts either an object (`{ "Authorization": "Bearer ..." }`) or an array of key/value pairs (`[{ "key": "Authorization", "value": "Bearer ..." }]`).
</ParamField>

<ParamField body="initialization_options" type="object">
  Optional MCP initialization options. Accepted and stored for parity with the dashboard; not currently exercised during the handshake.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.telzino.com/v1/mcp/test-connection \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://mcp.example.com/sse",
      "transport_type": "sse",
      "auth_headers": { "Authorization": "Bearer mcp-server-key" }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.telzino.com/v1/mcp/test-connection', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: 'https://mcp.example.com/sse',
      transport_type: 'sse',
      auth_headers: { Authorization: 'Bearer mcp-server-key' }
    })
  });

  const result = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.telzino.com/v1/mcp/test-connection',
      headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'},
      json={
          'url': 'https://mcp.example.com/sse',
          'transport_type': 'sse',
          'auth_headers': {'Authorization': 'Bearer mcp-server-key'}
      }
  )

  result = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "success": true,
    "message": "Success! Found 3 tools.",
    "toolCount": 3,
    "tools": [
      { "name": "search_kb", "description": "Search the knowledge base" },
      { "name": "create_ticket", "description": "Open a support ticket" },
      { "name": "get_order", "description": "Look up an order by id" }
    ]
  }
  ```

  ```json 200 Connection Failed theme={null}
  {
    "success": false,
    "message": "Connection failed"
  }
  ```

  ```json 400 Invalid Request theme={null}
  {
    "error": "Invalid request data",
    "details": [
      {
        "code": "invalid_string",
        "path": ["url"],
        "message": "Invalid MCP server URL"
      }
    ]
  }
  ```
</ResponseExample>

## 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`).

<Info>
  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](/api-reference/agents/create).
</Info>

## Troubleshooting

| `message`                      | Cause                                        | Solution                                               |
| ------------------------------ | -------------------------------------------- | ------------------------------------------------------ |
| `Invalid URL`                  | Malformed `url`                              | Provide a full URL including scheme (`https://`)       |
| `Connection failed`            | Server unreachable or rejected the handshake | Verify the URL, transport type, and auth headers       |
| Auth-related error from server | Missing/invalid credentials                  | Check `auth_headers` match what the MCP server expects |