How to Debug MCP Servers

If you're building AI agents with the Model Context Protocol (MCP), you've probably run into debugging nightmares. Your agent calls a tool, something breaks, and you're left staring at vague error messages with no idea what actually went over the wire.

Debugging MCP servers is hard. Here's why — and how to actually solve it.

What Are MCP Servers?

MCP (Model Context Protocol) is an open standard by Anthropic that lets AI agents call external tools. Think of it as an API layer between your LLM and the real world.

Your agent wants to create a JIRA ticket? There's an MCP server for that. Query a database? MCP server. Read a file? MCP server.

MCP servers expose tools (functions the agent can call), resources (data the agent can read), and prompts (templates the agent can use). The agent sends JSON-RPC 2.0 requests, the server executes the tool, and returns the result.

Simple in theory. In practice? Debugging these interactions is a mess.

Why Debugging MCP Servers Is Hard

When you debug MCP servers today, you're flying blind:

No wire trace — You can't see what your agent actually sent to the MCP server. Was the payload malformed? Did the handshake fail? Did the server crash silently? You have no idea.
No request replay — If a tool call fails, you can't just replay it with modified arguments. You have to restart your entire agent run and hope it happens again.
No payload inspection — MCP supports multiple transport types (HTTP, SSE, stdio). Each has its own quirks. Without seeing the raw request/response, you're guessing.
No handshake validation — Spec-compliant MCP servers require a two-step handshake (initialize → notifications/initialized) before any tool calls. If your server implementation is wrong, tool calls silently fail. Good luck debugging that.
No history — Once a tool call is done, it's gone. You can't go back and inspect what arguments were passed, what the response was, or how long it took.

This is why developers spend hours debugging MCP servers instead of building features.

The Current Options

Option 1: MCP Inspector

MCP Inspector is the official debugging tool from Anthropic. It's a good start, but it has serious limitations:

Requires npx and local install — You can't just open a browser and start debugging. You need Node.js, npm, and the right version installed.
No request replay — Once a tool call is done, you can't replay it. You have to manually re-enter arguments and hope you remember what failed.
No wire trace — You can see tool inputs and outputs, but you can't see the actual JSON-RPC requests going over the wire.
No diff view — When you modify arguments and retry a call, you can't see what changed between attempts.

MCP Inspector is fine for basic testing. But for real MCP server debugging, you need more.

Option 2: Console Logging

Some developers just add console.log() statements to their MCP server code. This works for simple bugs, but:

Doesn't help with protocol issues — If the handshake is wrong or the transport is misconfigured, logging inside your server won't catch it.
No historical context — Logs scroll by and disappear. You can't go back and inspect a failed call from 10 minutes ago.
Not portable — You have to modify your server code, restart it, and re-run your agent.

Option 3: Postman / cURL

You could manually craft JSON-RPC requests and send them with Postman or cURL. But:

You have to manually build every request — MCP handshakes, session IDs, tool schemas — all manual.
No auto-discovery — You can't browse available tools. You have to read the MCP server docs and hope they're up to date.
No live tracing — You can't see what your agent is sending in real time.

None of these options give you what you actually need: a full wire trace, request replay, and payload inspection in a browser-based tool.

That's where MCPRadar comes in.

How MCPRadar Solves MCP Server Debugging

MCPRadar is the debugger for MCP servers you actually need. Think Postman, but purpose-built for the Model Context Protocol.

Here's what makes it different:

1. Browser-Based — No Installation

Open mcpradar.dev and you're debugging. No npx, no local install, no dependencies. Works on any OS, any browser.

2. Full Wire Trace

Every JSON-RPC request and response is captured and displayed. You can see:

The exact payload your agent sent
The MCP server's response (or error)
The handshake sequence (initialize → notifications/initialized)
Transport details (HTTP headers, SSE stream chunks, etc.)

If something breaks, you know exactly why.

3. Request Replay with Diff

Made a typo in a tool argument? No problem. Click "Replay" on any tool call, modify the arguments, and send it again.

MCPRadar shows a diff view between the original and modified request, so you can see exactly what changed.

No restarting your agent. No losing context. Just instant iteration.

4. Two Modes: Server Test + Agent Debug

Server Test Mode — Connect your MCP server directly to MCPRadar. Browse available tools, build requests with a schema-driven form, and call them instantly. Pure Postman-style testing.

Agent Debug Mode — Point your AI agent at MCPRadar's proxy URL. Every tool call your agent makes appears in a live waterfall. Pause mid-run, edit arguments, resume, and replay individual steps.

Both modes give you full visibility into every MCP interaction.

5. Works with Localhost Servers

Developing locally? MCPRadar has two ways to connect to your localhost MCP server:

Bridge mode — Run npx mcpradar-bridge --port 3001 and your local server is instantly accessible from the deployed frontend.
Browser fallback — Let your browser connect directly (uses Chrome's "Local network access" permission).

No CORS issues. No SSRF workarounds. Just works.

6. Handshake Validation

MCPRadar automatically handles the MCP handshake for you. If your server requires initialize → notifications/initialized, MCPRadar sends it before every tool call.

If your server doesn't need the handshake (backward-compatible servers), MCPRadar detects that and skips it.

You don't have to think about it. It just works.

7. Multi-Transport Support

MCP has three transport types:

Streamable HTTP — Modern servers use this
SSE (Server-Sent Events) — Older community servers use this
stdio — Local process servers use this (via the bridge)

MCPRadar supports all three. It even has an Auto mode that tries Streamable HTTP first and falls back to SSE if needed.

8. Connection Profiles

Testing multiple MCP servers? Save connection profiles (URL + headers + transport) and switch between them with one click.

Dev, staging, production — all instantly accessible.

Real-World Use Cases

Here's how developers use MCPRadar to debug MCP servers:

Use Case 1: Handshake Debugging

Problem: Your agent connects to your MCP server, but tool calls return 404.

Solution: Open MCPRadar in Server Test Mode, connect to your server, and click "Browse Tools." MCPRadar shows you the exact handshake sequence and which step failed.

Turns out your server wasn't responding to initialize. Fix the bug, restart, and verify in MCPRadar. Done.

Use Case 2: Payload Inspection

Problem: Your agent sends a tool call with arguments, but the server crashes. You don't know if the issue is in the agent's LLM output or your server's validation logic.

Solution: Use MCPRadar in Agent Debug Mode. Point your agent at the proxy URL. Watch the tool call appear in the waterfall. Inspect the exact JSON payload.

The agent sent priority: "URGENT" but your server expects priority: "high". Fix the enum, replay the request, and it works.

Use Case 3: Transport Issues

Problem: Your MCP server works locally but fails when deployed. You suspect it's a transport issue (HTTP vs SSE).

Solution: Connect MCPRadar to your deployed server. Switch between HTTP and SSE transport modes. See which one works.

Your server was using SSE but didn't set the Content-Type: text/event-stream header. MCPRadar's wire trace showed the missing header. Fix it, redeploy, done.

Use Case 4: Iterative Argument Testing

Problem: You're building a new MCP tool with complex arguments (nested objects, arrays, enums). You need to test every edge case.

Solution: Use MCPRadar's Server Test Mode. The schema-driven form auto-generates inputs based on your tool's JSON Schema. Test every combination, replay with modifications, and verify the response.

No manual JSON crafting. No restarting your agent 20 times.

Getting Started with MCPRadar

Ready to debug MCP servers the right way? Here's how to get started:

Step 1: Connect Your Server

Go to mcpradar.dev
Click "Server Test Mode"
Enter your MCP server URL (e.g., http://localhost:3001/mcp)
Click "Connect"

MCPRadar discovers available tools and displays them in the sidebar.

Step 2: Test a Tool

Click on a tool in the sidebar
Fill in the arguments using the auto-generated form
Click "Call Tool"
See the response in real time

Step 3: Debug Your Agent

Click "Agent Debug Mode"
Click "+ New Session"
Enter your MCP server URL and click "Start Session"
Copy the proxy URL (e.g., https://mcpradar-production.up.railway.app/proxy/abc123)
Configure your AI agent to use the proxy URL instead of your real MCP server
Run your agent and watch every tool call appear in the MCPRadar dashboard

That's it. You're now debugging MCP servers like a pro.

Why MCPRadar Exists

We built MCPRadar because we were tired of debugging MCP servers the hard way.

Every AI developer hits the same problems:

"Why did my tool call fail?"
"What did my agent actually send?"
"How do I replay this with different arguments?"
"Is this a handshake issue or a server bug?"

MCP Inspector is a good start, but it's not enough for real development workflows.

We needed a tool that:

Works instantly in a browser (no install)
Shows the full wire trace (no guessing)
Supports request replay (no restarting agents)
Handles all transport types (HTTP, SSE, stdio)
Validates handshakes automatically (no manual setup)

So we built it.

MCPRadar is Postman for MCP servers. It's the debugger you reach for when you actually need to ship.

Try MCPRadar Now

If you're serious about building AI agents with MCP, you need a real debugger.

Start debugging at mcpradar.dev →

No installation. No configuration. Just open the browser and connect your server.

See every tool call. Replay any request. Debug MCP servers the way they should be debugged.

Questions? Feedback? We're building MCPRadar in public. If you have feature requests or want to share your debugging workflow, reach out to us at hello@mcpradar.dev.