MCP Debugger -- Test and Diagnose MCP Server Connections

Test any MCP server's standby URL with a real protocol handshake. MCP Debugger sends an initialize request, checks the JSON-RPC response, lists available tools, measures latency, and diagnoses common connection issues. Get a clear health report with actionable suggestions instead of staring at cryptic error messages in your MCP client.

MCP Debugger performs the same two-step handshake that Claude Desktop and other MCP clients do: (1) send a JSON-RPC initialize request with protocol version and client info, (2) send a tools/list request to discover available tools. It parses the response (including SSE-like multiline formats), checks for errors, measures latency, and produces a structured diagnostic report.

What data can you extract?

Data Point	Source	Example
Connection status	Initialize handshake	healthy, degraded, unhealthy, unreachable
Latency	Request timing	1200ms
Transport type	Response analysis	streamable-http
Protocol version	Server response	2025-03-26
Server name	Server info	counterparty-due-diligence-mcp
Available tools	tools/list response	3 tools: screen_counterparty, deep_dive, network_analysis
Issues	Diagnostic analysis	Authentication failed (HTTP 401)
Suggestions	Issue-specific fixes	Provide a valid API token

Why use MCP Debugger?

MCP servers on Apify run as standby actors -- always-on HTTP endpoints that accept JSON-RPC requests. When they don't work, the error messages from MCP clients are unhelpful: "connection failed", "transport error", or just silence. You're left guessing: Is the URL wrong? Is standby mode not enabled? Is authentication failing? Is the server responding with invalid JSON-RPC?

MCP Debugger replaces guesswork with diagnostics. It performs the exact protocol handshake that real MCP clients do, then tells you precisely what went wrong and how to fix it. The diagnostic engine maps specific HTTP status codes and error types to actionable suggestions.

Common problems MCP Debugger catches:

• Standby mode not enabled in actor.json (connection timeouts)
• Wrong URL path (404 -- missing /mcp suffix)
• Missing or incorrect authentication token (401/403)
• Server responding but not in JSON-RPC format (proxy or CDN interference)
• High cold-start latency masking as a connection failure
• Server responding to GET but not POST (wrong method)
• Server running but not registering any tools (empty tools/list)

Features

• Real MCP protocol handshake using the 2025-03-26 protocol version -- same as Claude Desktop and other production MCP clients
• SSE-compatible response parsing that handles both standard JSON responses and multiline SSE-like formats used by StreamableHTTPServerTransport
• Tool discovery via tools/list -- see every tool the server exposes with names and descriptions
• Issue-specific diagnostics that map HTTP status codes (401, 403, 404, 405), DNS errors, timeouts, and format errors to specific root causes
• Actionable suggestions for every detected issue -- not just "something's wrong" but "check that usesStandbyMode: true is set in actor.json"
• Latency measurement with severity levels: under 2s is healthy, 2-5s is moderate (likely cold start), over 5s is a warning
• URL normalization -- automatically adds https:// prefix and /mcp suffix if missing
• Four-level status classification: healthy (no issues), degraded (warnings only), unhealthy (errors), unreachable (connection failed)
• Optional authentication -- pass an API token for servers that require it
• Pay-per-event pricing at $0.15 per debug -- cheap enough for frequent health checks

Use cases for MCP debugging

Initial setup verification

Just deployed a new MCP server? Run MCP Debugger to verify: standby mode is working, the /mcp endpoint responds, tools are registered, and authentication works. Catch configuration issues before sharing the URL with users.

Health monitoring

Schedule MCP Debugger to run periodically against your MCP servers. Detect when servers go unhealthy due to expired tokens, standby timeout, or infrastructure changes. Alert your team before users report issues.

Client troubleshooting

A user reports "connection failed" with your MCP server. Run MCP Debugger to reproduce and diagnose the issue. The structured report shows exactly where the connection breaks.

Pre-release testing

Before publishing MCP server updates, run MCP Debugger against the staging URL to verify the handshake still works and all expected tools are registered.

Latency baseline

Measure cold-start and warm-start latency for your MCP servers. Run MCP Debugger twice in succession -- the first run triggers a cold start, the second measures warm latency. Compare against your SLA targets.

How to debug an MCP server

1. Enter the standby URL -- The full URL of the MCP server (e.g., https://username--actor-name.apify.actor/mcp).
2. Add an API token (optional) -- If the server requires authentication, provide your Apify API token.
3. Run the debug -- Click "Start" and wait for the handshake and tool discovery to complete.
4. Review the report -- Check connection status, latency, tool list, issues, and suggestions.

Input parameters

Parameter	Type	Required	Default	Description
standbyUrl	string	Yes	--	MCP server standby URL (e.g., https://username--actor-name.apify.actor/mcp). Protocol prefix and /mcp suffix are added automatically if missing.
apiToken	string	No	--	Apify API token for servers that require authentication. Sent as Authorization: Bearer <token>.

Input examples

Public MCP server:

{
    "standbyUrl": "https://ryanclinton--counterparty-due-diligence-mcp.apify.actor/mcp"
}

Authenticated MCP server:

{
    "standbyUrl": "https://ryanclinton--financial-crime-screening-mcp.apify.actor/mcp",
    "apiToken": "apify_api_YOUR_TOKEN_HERE"
}

Minimal URL (auto-normalized):

{
    "standbyUrl": "ryanclinton--my-mcp-server.apify.actor"
}

Output example

Healthy server

{
    "url": "https://ryanclinton--counterparty-due-diligence-mcp.apify.actor/mcp",
    "status": "healthy",
    "connectionSuccess": true,
    "latencyMs": 1200,
    "transport": "streamable-http",
    "protocolVersion": "2025-03-26",
    "serverName": "counterparty-due-diligence-mcp",
    "toolCount": 3,
    "tools": [
        { "name": "screen_counterparty", "description": "Screen a counterparty for risk factors" },
        { "name": "deep_dive", "description": "Deep investigation of a specific entity" },
        { "name": "network_analysis", "description": "Analyze corporate network connections" }
    ],
    "issues": [],
    "suggestions": [],
    "debuggedAt": "2026-03-18T14:30:00.000Z"
}

Unreachable server

{
    "url": "https://ryanclinton--nonexistent-mcp.apify.actor/mcp",
    "status": "unreachable",
    "connectionSuccess": false,
    "latencyMs": 5023,
    "transport": "unknown",
    "toolCount": 0,
    "tools": [],
    "issues": [
        { "severity": "error", "message": "Connection timed out — server may not be running" }
    ],
    "suggestions": [
        "Check that standby mode is enabled in actor.json (usesStandbyMode: true)",
        "Verify the actor has been run at least once to warm up standby"
    ],
    "debuggedAt": "2026-03-18T14:30:00.000Z"
}

Output fields

Field	Type	Description
url	string	The tested URL (after normalization)
status	string	Overall status: healthy, degraded, unhealthy, unreachable
connectionSuccess	boolean	Whether the initialize handshake succeeded
latencyMs	number	Round-trip time in milliseconds for the initialize request
transport	string	Detected transport type (e.g., streamable-http)
protocolVersion	string	MCP protocol version from server response (optional)
serverName	string	Server name from initialize response (optional)
toolCount	number	Number of tools the server exposes
tools	array	Tool list: { name, description? }
issues	array	Detected issues: `{ severity: "error"
suggestions	array	Actionable fix suggestions for detected issues
debuggedAt	string	ISO 8601 timestamp

Diagnostic mappings

Symptom	Diagnosed Issue	Suggestion
HTTP 401/403	Authentication failed	Provide a valid API token
HTTP 404	Endpoint not found	Check webServerMcpPath is /mcp in actor.json
HTTP 405	Method not allowed	Server exists but rejects POST on /mcp
Connection timeout	Server not running	Enable usesStandbyMode: true, run actor once
DNS failure	URL does not resolve	Check URL for typos
Non-JSON response	Proxy/CDN interference	Check if a proxy is intercepting requests
Latency > 5000ms	Cold start	First request after idle triggers warmup
0 tools returned	No tools registered	Check server.tool() calls are before transport connect

How much does it cost?

MCP Debugger uses pay-per-event pricing at $0.15 per debug. This covers the handshake, tool discovery, and diagnostic analysis.

Scenario	Debugs	Cost
One-off check	1	$0.15
Hourly monitoring (720/mo)	720	$108.00
Daily check across 50 servers	1,500	$225.00
CI/CD post-deploy (10/mo)	10	$1.50

The Apify Free plan ($5/mo credits) covers approximately 33 debug runs.

Run MCP debug using the API

Python

from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")

run = client.actor("ryanclinton/actor-mcp-debugger").call(run_input={
    "standbyUrl": "https://ryanclinton--counterparty-due-diligence-mcp.apify.actor/mcp",
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(f"Status: {item['status']} | Latency: {item['latencyMs']}ms | Tools: {item['toolCount']}")
    for tool in item["tools"]:
        print(f"  - {tool['name']}: {tool.get('description', '')}")
    for issue in item["issues"]:
        print(f"  [{issue['severity'].upper()}] {issue['message']}")
    for suggestion in item["suggestions"]:
        print(f"  → {suggestion}")

JavaScript

import { ApifyClient } from "apify-client";

const client = new ApifyClient({ token: "YOUR_API_TOKEN" });

const run = await client.actor("ryanclinton/actor-mcp-debugger").call({
    standbyUrl: "https://ryanclinton--counterparty-due-diligence-mcp.apify.actor/mcp",
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
const report = items[0];
console.log(`${report.status} | ${report.latencyMs}ms | ${report.toolCount} tools`);
report.tools.forEach(t => console.log(`  - ${t.name}`));
report.issues.forEach(i => console.log(`  [${i.severity}] ${i.message}`));

cURL

curl -X POST "https://api.apify.com/v2/acts/ryanclinton~actor-mcp-debugger/runs?token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"standbyUrl": "https://ryanclinton--counterparty-due-diligence-mcp.apify.actor/mcp"}'

FAQ

What MCP protocol version does the debugger use? The 2025-03-26 version, which is the current standard used by Claude Desktop and other production MCP clients.

Can I debug MCP servers that aren't on Apify? Yes. MCP Debugger sends standard HTTP requests. Any MCP server accessible via HTTP POST can be debugged, including self-hosted servers. Just provide the full URL.

What if my server uses SSE (Server-Sent Events) transport? MCP Debugger handles SSE-like multiline responses. It parses each line looking for valid JSON-RPC objects. Both single-response and multi-line formats are supported.

How do I know if my cold start latency is acceptable? Under 2 seconds is healthy. 2-5 seconds is moderate and typical for first requests after idle. Over 5 seconds indicates the actor may need optimization (smaller Docker image, fewer dependencies, lazy initialization).

Can I debug multiple MCP servers at once? Not in a single run. Run MCP Debugger separately for each server. Use the API to batch requests in parallel.

What's the 30-second timeout? MCP Debugger waits up to 30 seconds for the initialize response. If the server doesn't respond in 30 seconds, it's classified as unreachable. This is generous -- most MCP clients timeout after 10-15 seconds.

Why does my server show 0 tools? Common causes: (1) server.tool() calls happen after transport.handleRequest() -- tools must be registered before the connection. (2) The server crashes during initialization but sends a 200 response. (3) The tools/list endpoint isn't implemented.

Related actors

Actor	How to combine
Cloud Staging Test	Test actor output quality. MCP Debugger checks MCP protocol health; Cloud Staging Test checks output correctness.
Actor Health Monitor	Monitor runtime failures. Health Monitor catches crashes; MCP Debugger catches protocol-level issues.
Actor Test Runner	Functional testing. Test Runner validates output; MCP Debugger validates connectivity.

Support

Found a bug or have a feature request? Open an issue in the Issues tab on this actor's page.