MCP Debugger

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?

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

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

Diagnostic mappings

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.

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

Support

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