# MCP Server Debugger — Test & Troubleshoot Standby Connections (`ryanclinton/actor-mcp-debugger`) Actor Actor Mcp Debugger. Available on the Apify Store with pay-per-event pricing. - **URL**: https://apify.com/ryanclinton/actor-mcp-debugger.md - **Developed by:** [Ryan Clinton](https://apify.com/ryanclinton) (community) - **Categories:** AI, Developer tools - **Stats:** 2 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## 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 `. | #### Input examples **Public MCP server:** ```json { "standbyUrl": "https://ryanclinton--counterparty-due-diligence-mcp.apify.actor/mcp" } ```` **Authenticated MCP server:** ```json { "standbyUrl": "https://ryanclinton--financial-crime-screening-mcp.apify.actor/mcp", "apiToken": "apify_api_YOUR_TOKEN_HERE" } ``` **Minimal URL (auto-normalized):** ```json { "standbyUrl": "ryanclinton--my-mcp-server.apify.actor" } ``` ### Output example #### Healthy server ```json { "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 ```json { "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" | "warning" | "info", message }` | | `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 ```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 ```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 ```bash 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](https://apify.com/ryanclinton/cloud-staging-test) | Test actor output quality. MCP Debugger checks MCP protocol health; Cloud Staging Test checks output correctness. | | [Actor Health Monitor](https://apify.com/ryanclinton/actor-health-monitor) | Monitor runtime failures. Health Monitor catches crashes; MCP Debugger catches protocol-level issues. | | [Actor Test Runner](https://apify.com/ryanclinton/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](https://console.apify.com/actors) on this actor's page. # Actor input Schema ## `standbyUrl` (type: `string`): The MCP server standby URL (e.g. https://username--actor-name.apify.actor/mcp) ## Actor input object example ```json { "standbyUrl": "https://ryanclinton--counterparty-due-diligence-mcp.apify.actor/mcp" } ``` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "standbyUrl": "https://ryanclinton--counterparty-due-diligence-mcp.apify.actor/mcp" }; // Run the Actor and wait for it to finish const run = await client.actor("ryanclinton/actor-mcp-debugger").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "standbyUrl": "https://ryanclinton--counterparty-due-diligence-mcp.apify.actor/mcp" } # Run the Actor and wait for it to finish run = client.actor("ryanclinton/actor-mcp-debugger").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "standbyUrl": "https://ryanclinton--counterparty-due-diligence-mcp.apify.actor/mcp" }' | apify call ryanclinton/actor-mcp-debugger --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=ryanclinton/actor-mcp-debugger", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "MCP Server Debugger — Test & Troubleshoot Standby Connections", "description": "Actor Mcp Debugger. Available on the Apify Store with pay-per-event pricing.", "version": "1.0", "x-build-id": "ooNlqVc3lh7QKJqmk" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/ryanclinton~actor-mcp-debugger/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-ryanclinton-actor-mcp-debugger", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/ryanclinton~actor-mcp-debugger/runs": { "post": { "operationId": "runs-sync-ryanclinton-actor-mcp-debugger", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/ryanclinton~actor-mcp-debugger/run-sync": { "post": { "operationId": "run-sync-ryanclinton-actor-mcp-debugger", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "standbyUrl" ], "properties": { "standbyUrl": { "title": "Standby URL", "type": "string", "description": "The MCP server standby URL (e.g. https://username--actor-name.apify.actor/mcp)" } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```