MCP TraceLab
Free browser-based MCP debugger

Debug MCP JSON-RPC logs before guessing at the fix

MCP TraceLab is a free MCP debugger that matches JSON-RPC request IDs, checks the initialize handshake, identifies tool-call and stdio failures, redacts common secrets, and turns raw logs into a practical fix list—entirely inside your browser.

Inspect my MCP log ↓
Free, no signup Works with an included sample Data stays on your device
MCP server not connecting Initialize timeout tools/call -32602 stdio JSON errors
MCP TraceLab interface displaying MCP requests, responses and protocol diagnostics
JSON-RPC IDs matched
Secrets redacted locally
Free, no signup Open the tool and inspect a log immediately
Browser-local processing Pasted and opened logs are not uploaded
Multiple log formats JSON, JSONL and timestamped captures
Actionable export Download a redacted Markdown report
MCP log inspector

Find MCP handshake and tool-call errors in your log

Paste a client or server capture below. The inspector reconstructs the JSON-RPC timeline, matches IDs, highlights protocol failures and recommends the next check.

Local-only analysis
Drop .json, .jsonl, .log or .txt

Privacy: analysis and redaction run in this page. Before sharing any export, still review it for project-specific secrets.

What the MCP debugger checks

From raw JSON-RPC messages to a focused fix list

Each check answers a concrete debugging question: what was sent, what returned, what is missing and where the protocol first diverged.

Request and response ID matching

Pair JSON-RPC requests with responses, then flag missing responses, duplicate request IDs and orphan responses that cannot be tied to a request.

MCP handshake and tool diagnostics

Check the initialize flow, initialized notification, protocol version, tools/call failures and returned JSON-RPC error codes.

Local redaction and report export

Mask common credentials before display and export a Markdown report with reproducible evidence, fixes to try and a redacted timeline.

How to debug MCP logs

Go from “MCP server not connecting” to the next test in three steps

Preserve the failing capture, isolate the first broken protocol expectation, and rerun one controlled change at a time.

01

Paste or open the failing log

Include the initialize exchange and the request that failed. You can use JSON, JSONL or a timestamped client/server capture.

02

Read the first actionable diagnostic

Start with the earliest missing response, handshake break, error object or non-JSON stdio line instead of changing several settings at once.

03

Apply one fix and compare

Rerun the same client action, inspect the new timeline and export the redacted report when you need to share reproducible evidence.

Practical MCP troubleshooting playbook

MCP error fixes you can use now

Each example follows the same pattern: identify the failing message, confirm the observable result, then apply the smallest configuration or code correction.

Fix an MCP initialize timeout or failed handshake

Use when the client reports “server disconnected,” “initialize timed out” or never lists tools.

initialize → no response

1 Expected messages

→ {"jsonrpc":"2.0","id":1,
   "method":"initialize", ...}

← {"jsonrpc":"2.0","id":1,
   "result":{
     "protocolVersion":"...",
     "capabilities":{},
     "serverInfo":{...}
   }}

→ {"jsonrpc":"2.0",
   "method":"notifications/initialized"}

2 What to verify

  1. The server process starts and stays running.
  2. The response uses the same ID as initialize.
  3. The response contains protocolVersion and capabilities.
  4. The client sends notifications/initialized.

3 Configuration fix

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": [
        "/absolute/path/server.js"
      ],
      "env": {
        "LOG_LEVEL": "error"
      }
    }
  }
}

Fix MCP tools/call error -32602: Invalid params

Use when a tool is discovered successfully but fails as soon as the client invokes it.

JSON-RPC -32602

1 Failing request

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "search_docs",
    "arguments": {
      "limit": "10"
    }
  }
}

2 Observable result

{
  "jsonrpc": "2.0",
  "id": 12,
  "error": {
    "code": -32602,
    "message": "Invalid params"
  }
}

In this example, limit was sent as a string. Compare every argument with the tool’s published inputSchema.

3 Corrected request

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "search_docs",
    "arguments": {
      "limit": 10
    }
  }
}

Fix non-JSON stdout output in an MCP stdio server

Use when the client reports malformed JSON, an unexpected token or a connection that closes immediately.

stdio parse failure

1 Problem output

Server started on port 3000
{"jsonrpc":"2.0","id":1,"result":{...}}

The banner is not a JSON-RPC message. On a stdio transport, the client may attempt to parse it as protocol data.

2 Correct stream split

  • stdout: MCP protocol messages only.
  • stderr: startup messages, diagnostics and debug logs.
  • Disable library banners and progress output.
  • Do not pretty-print multi-line transport frames unless the transport supports it.

3 Minimal code fix

// Avoid for application logs:
console.log("Server started");

// Write diagnostics to stderr:
console.error("Server started");

// Keep protocol writes on stdout:
process.stdout.write(
  JSON.stringify(message) + "\n"
);
MCP debugging FAQ

Common questions about MCP logs and JSON-RPC errors

Short answers for the failure modes developers most often need to isolate before changing client or server configuration.

What is an MCP debugger?

An MCP debugger analyzes Model Context Protocol JSON-RPC messages so you can follow initialize requests, responses, notifications, tool calls and errors in execution order. MCP TraceLab focuses on log evidence: matching IDs, identifying missing messages and showing the next protocol check.

Does MCP TraceLab upload my logs?

No. Parsing, analysis, redaction and Markdown generation run locally in your browser. The page does not need to send pasted text or opened files to a server. Because project-specific secret formats vary, review any downloaded report before sharing it.

How do I debug an MCP server that is not connecting?

First confirm that the configured command starts the intended process. Then capture the initialize request and verify a response returns with the same ID. Check protocolVersion, capabilities, the subsequent notifications/initialized message and non-JSON stdout. See the initialize timeout walkthrough.

How do I find an MCP request with no response?

Every JSON-RPC request containing an id should be paired with a response carrying that same ID. Paste both directions of the capture into the inspector. It reports unmatched requests, duplicate request IDs and responses for which no request appears in the supplied log.

Why can stdout output break an MCP stdio server?

A stdio client expects protocol data on stdout. Startup banners, debug statements and progress messages may be parsed as JSON-RPC and trigger malformed JSON errors. Send application diagnostics to stderr and reserve stdout for protocol messages. Use the stdio stream example.

What does JSON-RPC error -32602 mean in tools/call?

Error -32602 means invalid parameters. Compare params.arguments with the tool’s inputSchema: required properties, number versus string types, enum values, nested object shapes and unexpected keys. See the corrected tools/call example.

Which MCP log formats can I inspect?

You can inspect a JSON array, JSON Lines, a single JSON-RPC object, concatenated multi-line objects or a capture with timestamps and direction labels around the JSON. Wrapper objects using common fields such as message, payload, request or response are also examined.

What secrets are automatically redacted?

The local redactor masks common authorization headers, bearer tokens, API keys, access and refresh tokens, passwords, cookies, private keys, JWT-like strings and sensitive URL query parameters. It is a safety aid, not a guarantee against every proprietary credential format.

Keep the evidence

Download an MCP debugging report you can use today

Get a Markdown checklist immediately. If you have analyzed a log, the download also includes its diagnostics, matched-request summary and redacted timeline.

Free · no signup · generated locally on your device