How to Debug an MCP Server by Seeing the Real HTTP Traffic

To debug an MCP server, put a proxy between the MCP client and your server so you can read the real JSON-RPC messages. The official MCP Inspector connects as its own client and never sees what Claude or Cursor actually sends. Route the Streamable HTTP transport through APXY and inspect every tools/list, tools/call, request body, and error in the real data path.

Why MCP servers are hard to debug

The Model Context Protocol uses JSON-RPC 2.0 over one of two transports: stdio for local subprocess servers, and Streamable HTTP (HTTP POST plus an SSE stream) for hosted and remote servers. Almost everything that fails in an MCP server fails on the wire: a malformed tools/list schema, a tools/call that returns the wrong content shape, a missing or rotated Mcp-Session-Id header, an auth token that never reaches your handler.

None of that is visible from your server logs alone. When a tool call silently does nothing in Claude, you cannot tell from the server side whether the client sent a malformed request, whether your response violated the schema, or whether the transport dropped the SSE stream. You are debugging blind.

The official Inspector cannot see real client traffic

The first tool everyone reaches for is the official MCP Inspector (npx @modelcontextprotocol/inspector). It is genuinely useful for poking at a server in isolation — listing tools, firing a call, checking the response.

But there is a structural limit: the Inspector is its own MCP client. It connects to your server and sends its requests. It cannot sit between Claude and your server and watch the actual production interaction. So the request that fails in Claude is not the request the Inspector sends. When the bug only reproduces with the real client — a specific argument shape, a header the host injects, a session lifecycle quirk — the Inspector shows you a green checkmark while Claude shows you nothing.

To debug the real interaction you need something in the real data path. That is what a capturing proxy does.

Put APXY in the data path

APXY is a local proxy that captures and inspects HTTP(S) traffic. Because the MCP Streamable HTTP transport is just HTTP, routing the client's traffic through APXY captures every JSON-RPC message exactly as Claude or Cursor sent it.

1. Start the proxy

apxy start

This starts the local proxy and registers it as the system proxy so client traffic flows through it. If you only want to capture one process and leave the rest of your machine alone:

apxy start --no-system-proxy --port 8080

Then point only the MCP client at it. Most MCP clients and SDKs honor the standard HTTP_PROXY / HTTPS_PROXY environment variables, so launching the host (or a locally spawned HTTP MCP server) with HTTPS_PROXY=http://127.0.0.1:8080 is enough to route just that connection.

2. Reproduce the failure

Trigger the broken behavior the normal way: ask Claude or Cursor to use the tool that misbehaves. Every request the client makes to your MCP server endpoint is now captured — the initialize handshake, tools/list, tools/call, and the SSE responses coming back.

3. Read the real JSON-RPC

apxy logs list
apxy logs show <id>

logs list shows the captured exchanges; logs show prints the full request and response for one of them — method, headers, the JSON-RPC envelope, and the body. This is where MCP bugs become obvious:

• Schema mismatches — the result of your tools/list does not match what the client expects, so the tool never appears.
• Wrong content shape — tools/call returns a bare string where the spec wants a content array, so the host discards it.
• Session header problems — the Mcp-Session-Id the client sends does not match what your server issued, so every call 400s.
• Auth that never arrives — the Authorization header you assumed was set is missing or stripped before it reaches your handler.

You are no longer guessing from server logs. You are reading the exact bytes that crossed the connection.

4. Diff a working call against a broken one

When one tool works and another does not, capture both and compare:

apxy logs diff <good-id> <bad-id>

The diff highlights the header and body differences between a request that succeeded and one that failed — usually the fastest path to the root cause.

5. Replay without re-running the agent

Iterating by asking the agent to retry is slow and non-deterministic. Once a failing request is captured, replay it directly against your server after each code change:

apxy logs replay <id>

Same request, every time, until the response is correct. No token spend, no waiting on the model.

Hand the captured traffic to your AI agent

The reason this matters for MCP specifically: you are usually debugging an MCP server with an AI agent. Agents read code well but cannot see the network. Export the captured exchange and give it to the agent as evidence:

apxy logs export-curl <id>

Now Claude Code or Cursor can reason from the actual request and response instead of from what your server code should produce. This is the same pattern described in why your AI coding agent needs network visibility — it applies cleanly to MCP, where the gap between intended and actual protocol behavior is exactly where servers break.

A note on stdio servers

If your MCP server uses the stdio transport, traffic flows over pipes, not HTTP, so a network proxy does not apply directly. The practical move is to develop and debug against the Streamable HTTP transport — most SDKs support both, and HTTP is what hosted and remote MCP servers use in production anyway. Debug over HTTP with full visibility, ship either transport.

Frequently asked questions

Why can't I just use the MCP Inspector?

The Inspector connects to your server as its own client. It cannot observe the requests Claude or Cursor actually send, so any bug that only reproduces with the real host stays invisible. A proxy sits in the real data path and shows you the actual traffic.

Does APXY work with the Streamable HTTP transport and SSE?

Yes. The Streamable HTTP transport is HTTP POST plus an SSE response stream. APXY captures both the request and the streamed response, so you see the full JSON-RPC exchange.

Can I capture only the MCP client and nothing else on my machine?

Yes. Run apxy start --no-system-proxy and point only the client at the proxy with HTTPS_PROXY=http://127.0.0.1:<port>. The rest of your machine's traffic is untouched.

How do I debug a tool call that silently does nothing in Claude?

Capture the tools/call request with APXY and run apxy logs show <id>. The silent failure is almost always a response that violates the content schema or a session-header mismatch — both visible immediately in the captured exchange.

Can my AI agent use the captured MCP traffic?

Yes. Export it with apxy logs export-curl <id> and paste it into Claude Code or Cursor. The agent can then diagnose the protocol error from real evidence instead of guessing from your server code.

Summary

MCP servers fail on the wire, and the official Inspector — by design — never sees the wire when the real client is talking. Put APXY in the data path, reproduce the failure once, and read, diff, and replay the exact JSON-RPC the client sent. Pair it with your AI agent and protocol bugs stop being guesswork.

Install APXY for free and capture your first MCP exchange in under five minutes. If you build MCP servers with an AI agent, see APXY with Claude Code and APXY with Cursor.