Skip to main content

​
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

1

Initialize

POST /sse with initialize request
2

Read Response

Read SSE stream for response
3

List Tools

POST /sse with tools/list request
4

Parse

Parse tool definitions
5

Display

Display results in UI

​
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):
1

Retry 1

Wait 9 seconds, try again
2

Retry 2

Wait 9 seconds, try again
3

Retry 3

Wait 9 seconds, try again
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

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

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

{
  "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: 
import logging
logging.basicConfig(level=logging.DEBUG)

​
Check Server Logs

Fly.io: 
fly logs --app your-app
Local: 
tail -f server.log

​
Verify Network

Test connectivity: 
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

Test Locally First

Validate your MCP works on localhost before deploying

Use curl

Test manually with curl to isolate issues

Check Logs

Review server logs for detailed error messages

Start Simple

Test without auth first, then add complexity

​
Troubleshooting Guide

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
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
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
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

​
Next Steps

Remote Deployment

Deploy your MCP to production

Create Scenarios

Build test cases for your MCP

Claude Desktop Setup

Connect Claude Desktop to your MCP

API Reference

Complete API documentation