> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heymcp.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# How it works

> What connects to what, and why nothing is ever buffered.

## The path a request takes

```
  Agent client                                    Your machine
  (Claude, ChatGPT,        ┌──────────────┐
   Grok, Cursor…)          │  HeyMCP edge │       ┌──────────────┐
        │                  │              │       │  heymcp CLI  │
        │  HTTPS           │  routing     │  WSS  │              │
        └─────────────────►│  · policy    │◄─────►│              │
   https://amber-jetty     │  · the tee   │       └──────┬───────┘
     .t.heymcp.dev/mcp     └──────┬───────┘              │ HTTP
                                  │                      ▼
                                  │ events        localhost:8000/mcp
                                  ▼               (your MCP server)
                          ┌──────────────┐
                          │  Inspector   │
                          │  timeline    │
                          └──────────────┘
```

Three things worth noticing:

**The CLI dials out.** The WebSocket to the edge is an outbound connection from
your machine. Nothing inbound is opened, no port is forwarded, and your router
and firewall don't need to know anything about this.

**Your server sees an ordinary local request.** The CLI forwards each one to
`127.0.0.1` (or `myapp.test`, or wherever you pointed it) exactly as it arrived,
with the `Host` header rewritten to your local target. Self-signed certificates
are accepted deliberately, because Herd and Valet use them.

**The timeline is a copy, not a checkpoint.** The edge forwards each chunk of
the response the instant it arrives and hands a *copy* to the inspector
afterwards. Forward first, inspect second — always in that order.

## Why "never buffer" matters

MCP streams over Server-Sent Events. A proxy that waits for a complete response
body before passing it on turns every streaming response into a hang: the agent
sits there receiving nothing until the server finishes, which for a long-running
tool call may be minutes.

So the edge streams. Its regression test fires a reference server one byte at a
time and asserts the SSE frame terminators survive. The production TLS layer
disables response buffering for the same reason.

The practical consequence for you: **a slow tool call looks slow, not broken**,
and partial output reaches the agent as it's produced.

## The parts

<AccordionGroup>
  <Accordion title="The CLI (heymcp)">
    A single static Rust binary. Holds the WebSocket to the edge, multiplexes
    many concurrent agent requests over it, forwards each to your local server,
    and reconnects with jittered backoff when the network blips. It also runs
    the [handshake probe](/concepts/the-probe) locally for `heymcp probe`.
  </Accordion>

  <Accordion title="The edge">
    Terminates TLS, resolves the hostname to your tunnel, applies
    [path policy](/concepts/urls-and-paths#what-is-shared) and any
    [bearer requirement](/security/authentication), and streams the exchange
    both ways. It also parses MCP frames as they pass, which is where the
    timeline comes from.

    Every failure at the edge answers with a real HTTP status code **and** a
    JSON-RPC error object, because agents are not browsers and an HTML error
    page is an unretryable, confusing failure inside a client. See
    [Troubleshooting](/troubleshooting#edge-error-codes).
  </Accordion>

  <Accordion title="The inspector">
    The web app at [app.heymcp.dev](https://app.heymcp.dev). Receives events
    over a websocket as they happen, folds request/response pairs into single
    rows, and keeps history for as long as your plan's
    [retention window](/account/plans-and-limits) allows.
  </Accordion>
</AccordionGroup>

## What happens when something goes wrong

| Situation                              | What the agent gets                                                                                                               |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Your local server is slow              | The response streams as it's produced. No buffering.                                                                              |
| Your local server errors               | Its real response, forwarded untouched. HeyMCP doesn't rewrite your errors.                                                       |
| Your local server sends malformed JSON | Forwarded untouched. The inspector records it as an opaque frame rather than dropping it. A parse failure never blocks a forward. |
| You stop `heymcp share`                | **503** with a JSON-RPC body, so the client retries later rather than concluding the connector is gone.                           |
| The hostname isn't yours               | 404.                                                                                                                              |
| Your laptop's network drops            | The CLI reconnects with backoff and, within 15 minutes, resumes the *same* session so your timeline isn't forked in two.          |