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

# Testing MCP Connections

> Test and validate your MCP server connections

## Overview

The Surfa platform includes a built-in connection tester to validate your MCP setup before creating test scenarios.

## Using the Test Connection Feature

### 1. Navigate to MCP Settings

Go to **Settings → MCP** in your Surfa workspace.

### 2. Add Your MCP

Click **Add New MCP** and fill in:

* **Name:** Descriptive name (e.g., "Production Surfa MCP")
* **Transport:** SSE, STDIO, or Streamable HTTP
* **Endpoint:** Your MCP URL (e.g., `https://surfa-mcp.fly.dev/sse`)
* **Headers:** Authentication headers (optional)

### 3. Click "Test Connection"

The platform will:

1. Send an `initialize` request
2. Send a `tools/list` request
3. Parse the response
4. Display discovered tools

## What Happens During Testing

### For SSE Transport

<Steps>
  <Step title="Initialize">
    POST /sse with initialize request
  </Step>

  <Step title="Read Response">
    Read SSE stream for response
  </Step>

  <Step title="List Tools">
    POST /sse with tools/list request
  </Step>

  <Step title="Parse">
    Parse tool definitions
  </Step>

  <Step title="Display">
    Display results in UI
  </Step>
</Steps>

### Success Response

```
✅ Connection successful!
Discovered 4 tools:
- get_analytics
- query_events
- find_highest_latency
- get_session
```

### Retry Behavior

If the server returns `202 Accepted` (machine starting):

<Steps>
  <Step title="Retry 1">
    Wait 9 seconds, try again
  </Step>

  <Step title="Retry 2">
    Wait 9 seconds, try again
  </Step>

  <Step title="Retry 3">
    Wait 9 seconds, try again
  </Step>
</Steps>

You'll see progress messages:

```
Retry attempt 1 of 3... (waiting for server to start)
Retry attempt 2 of 3... (waiting for server to start)
✅ Connection successful!
```

## Common Test Results

### ✅ Success

**Message:** "Connection successful!"

**Tools:** List of discovered tools displayed

**Next:** Create test scenarios

***

### ⚠️ Cold Start (202)

**Message:** "Retry attempt X of 3..."

**Action:** Wait for retries to complete

**Duration:** Up to 27 seconds

***

### ❌ Timeout

**Message:** "Machine is starting up but taking longer than expected"

**Cause:** Server not responding after 27 seconds

**Fix:**

* Check server is running
* Increase timeout
* Configure always-on

***

### ❌ Unauthorized (401)

**Message:** "Authentication failed"

**Cause:** Invalid API key or missing headers

**Fix:**

* Verify API key
* Check Authorization header format
* Ensure key has correct permissions

***

### ❌ Not Found (404)

**Message:** "Endpoint not found"

**Cause:** Wrong URL or path

**Fix:**

* Verify endpoint URL
* Check transport type matches
* Test with curl first

***

### ❌ No Tools Found

**Message:** "Connection successful but no tools discovered"

**Cause:** `tools/list` returned empty array

**Fix:**

* Check MCP server has tools defined
* Verify tools are registered
* Test `tools/list` manually

## Manual Testing with curl

### Test Initialize

```bash theme={null}
curl -X POST https://your-mcp.fly.dev/sse \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "test-init",
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "test-client", "version": "1.0.0"}
    }
  }'
```

### Test Tools List

```bash theme={null}
curl -X POST https://your-mcp.fly.dev/sse \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "test-tools",
    "method": "tools/list",
    "params": {}
  }'
```

### Expected Response

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "test-tools",
  "result": {
    "tools": [
      {
        "name": "get_analytics",
        "description": "Get analytics metrics",
        "inputSchema": {
          "type": "object",
          "properties": {},
          "required": []
        }
      }
    ]
  }
}
```

## Debugging Failed Tests

### Enable Debug Logging

**In Surfa Platform:**

Check browser console (F12) for detailed logs:

```
Initialize response: {...}
Tools/list response status: 200
Found tools in response: [...]
```

**In Your MCP Server:**

```python theme={null}
import logging
logging.basicConfig(level=logging.DEBUG)
```

### Check Server Logs

**Fly.io:**

```bash theme={null}
fly logs --app your-app
```

**Local:**

```bash theme={null}
tail -f server.log
```

### Verify Network

**Test connectivity:**

```bash theme={null}
ping your-mcp.fly.dev
curl -I https://your-mcp.fly.dev
```

**Check firewall:**

* Ensure port 443 (HTTPS) is open
* Verify no VPN blocking requests

## Best Practices

<CardGroup cols={2}>
  <Card title="Test Locally First" icon="house">
    Validate your MCP works on localhost before deploying
  </Card>

  <Card title="Use curl" icon="terminal">
    Test manually with curl to isolate issues
  </Card>

  <Card title="Check Logs" icon="file-lines">
    Review server logs for detailed error messages
  </Card>

  <Card title="Start Simple" icon="seedling">
    Test without auth first, then add complexity
  </Card>
</CardGroup>

## Troubleshooting Guide

<AccordionGroup>
  <Accordion title="Connection times out" icon="clock">
    **Possible causes:**

    * Server is starting (cold start)
    * Network issues
    * Firewall blocking requests

    **Solutions:**

    * Wait for retry logic to complete
    * Check server status: `fly status`
    * Test with curl to verify connectivity
  </Accordion>

  <Accordion title="Tools not showing" icon="wrench">
    **Possible causes:**

    * MCP server not returning tools
    * Wrong endpoint path
    * Tools not registered

    **Solutions:**

    * Test `tools/list` manually with curl
    * Verify endpoint URL is correct
    * Check server logs for errors
  </Accordion>

  <Accordion title="Authentication errors" icon="key">
    **Possible causes:**

    * Invalid API key
    * Wrong header format
    * Missing Authorization header

    **Solutions:**

    * Verify API key is correct
    * Use format: `Bearer sk_live_...`
    * Check headers are set in MCP config
  </Accordion>

  <Accordion title="JSON parse errors" icon="code">
    **Possible causes:**

    * Invalid JSON response
    * Server returning HTML instead of JSON
    * CORS issues

    **Solutions:**

    * Check server is returning valid JSON
    * Verify Content-Type header
    * Enable CORS if needed
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Remote Deployment" icon="cloud" href="/remote-mcp-deployment">
    Deploy your MCP to production
  </Card>

  <Card title="Create Scenarios" icon="list-check" href="/quickstart">
    Build test cases for your MCP
  </Card>

  <Card title="Claude Desktop Setup" icon="sparkles" href="/claude-desktop-setup">
    Connect Claude Desktop to your MCP
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference">
    Complete API documentation
  </Card>
</CardGroup>