Skip to main content

​
Start here

Almost every “it doesn’t work” resolves to one of three questions, and they’re worth asking in this order:
1

Does the handshake report say anything?

Two findings block clients completely and are invisible from your side: transport/content-type and transport/accept-sse. Rule these out before touching anything else.
2

Did the request reach the inspector?

Open your session’s timeline and try the client again.
  • Nothing appears → the client never reached the edge. It’s the URL, or the tunnel isn’t running.
  • Rows appear → the client got through. The problem is between the edge and your server, or in your server, and the timeline will show you which.
3

What does the error code say?

Every edge failure carries a JSON-RPC code. The table below decodes them.

​
Edge error codes

Every failure at the edge answers with a real HTTP status and a JSON-RPC error object, because an HTML error page is an unretryable, confusing failure inside an agent client.
The 404-vs-503 split is deliberate. An unknown hostname gets 404; a known hostname with no live tunnel gets 503. That’s so clients retry rather than concluding the connector is gone and quietly forgetting it.

​
The connector doesn’t appear

The client never reached the edge.
  • Check the URL character by character. It must end in /mcp.
  • Confirm heymcp share is still running in your terminal.
  • curl -i https://your-slug.t.heymcp.dev/mcp — a 503 means the tunnel is down, a 404 means the hostname or path is wrong, and a JSON-RPC response means the tunnel is fine and the problem is client-side.
Your server accepted initialize and then something went wrong. Expand the INIT← row to see exactly what it answered.An OPAQUE row here usually means an HTML error page where JSON was expected — a framework exception page, most often.
Claude.ai fails silently, with nothing in the UI. Work through the Claude.ai troubleshooting list, which is ordered by how often each cause is the answer.

​
The tools are never called

The client connected and can see your tools, and is choosing not to use them. This is a schema problem, not a transport one.

​
The tool is called, and fails

Expand the row in the inspector. You can see the arguments the agent actually sent, which is usually the surprise. Fix your server, then hit Try it again on the row to replay that exact call without waiting for the agent to reproduce it.

​
Streaming problems

Not HeyMCP — the edge forwards each chunk the instant it arrives and never buffers. Something in your own stack is buffering: output buffering in PHP, a reverse proxy in front of your dev server, or a framework helper that collects the whole body before sending.
The edge allows 30 seconds to the first byte and 300 seconds of idle time after that. A tool that takes minutes needs to send something — a keep-alive SSE comment is enough — rather than going silent.
More than 2,000 events buffered for one session, so the oldest were dropped. The marker is there so a gap in the timeline is never silent. Nothing was lost on the wire — this only affects what the inspector kept.

​
Tunnel and CLI problems

3 on Hobby, 10 on Pro. heymcp sessions shows what’s live; closing the terminal frees the slot.
Normal on a flaky network — the CLI backs off and retries, quietly for the first 30 seconds. Reconnecting within 15 minutes resumes the same session, so your timeline isn’t forked.
The install directory isn’t on your PATH. The installer names the file it edited; open a new terminal, or source it. See Installation.
Your CLI is older than your server. Update it:
Both are Pro. Check with heymcp whoami. For a domain, also confirm it’s verified and active on the Domains page.

​
Still stuck

Export the session and you have the whole exchange in one file:
That’s a much better bug report than a description, because it contains what the client actually sent rather than what anyone thinks it sent.