> ## 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.

# Claude Code

> One command, and the best error messages of any client.

Claude Code is the right place to start. It's the most permissive of the
clients, it accepts a static bearer token, and when something is wrong it says
so in the transcript instead of failing silently.

## Add the connector

```bash theme={null}
heymcp share localhost:8000
```

Then, with the URL it printed:

```bash theme={null}
claude mcp add --transport http heymcp https://amber-jetty.t.heymcp.dev/mcp
```

That's it. `claude mcp add` confirms with an `Added …` line.

<Note>
  `--transport http` is the streamable HTTP transport, which is what HeyMCP
  serves. You may see it called `streamable-http` in MCP specs and in server
  documentation; Claude Code accepts that name as an alias in JSON config.
</Note>

## With a bearer token

If you shared with [`--bearer`](/security/authentication):

```bash theme={null}
heymcp share localhost:8000 --bearer s3cret
```

```bash theme={null}
claude mcp add --transport http heymcp https://amber-jetty.t.heymcp.dev/mcp \
  --header "Authorization: Bearer s3cret"
```

Claude Code is the only client of the seven where this is a one-liner, which is
another reason to prove your setup here first.

## Choosing where the config is saved

```bash theme={null}
claude mcp add --transport http heymcp <url> --scope user
```

`--scope` (short form `-s`) controls whether the server is recorded for this
project or for you globally. A tunnel URL is usually a per-project thing, so the
default is normally what you want.

## Check it connected

```bash theme={null}
claude mcp list
```

You want `✔ Connected` next to `heymcp`. The other statuses are informative:

| Status                   | Meaning                                                                     |
| ------------------------ | --------------------------------------------------------------------------- |
| `✔ Connected`            | Working.                                                                    |
| `! Needs authentication` | The server wants credentials Claude Code doesn't have.                      |
| `✘ Failed to connect`    | Claude Code appends the HTTP status and any error text the server returned. |

Inside a session, `/mcp` opens a panel showing each server, its tool count, and
its detail view.

## Try it

Ask Claude to use one of your tools, then watch the row appear in your HeyMCP
inspector. You'll see the arguments it actually sent — which is regularly the
surprising part.

<h2 id="its-not-showing-up">
  It's not showing up
</h2>

<AccordionGroup>
  <Accordion title="claude mcp list says Failed to connect">
    Claude Code prints the status code and the server's error text. Match it
    against the [edge error codes](/troubleshooting#edge-error-codes) — a 503
    means your tunnel isn't running, a 404 means the URL is wrong or the path
    isn't shared.
  </Accordion>

  <Accordion title="Connected, but the tools never get called">
    Check the [handshake report](/concepts/the-probe) — most often a tool has no
    description, so Claude has nothing to go on but the name.
    [`tool/no-description`](/lint#tool-no-description)
  </Accordion>

  <Accordion title="Needs authentication">
    Either you shared with `--bearer` and didn't pass `--header`, or your own
    server is requiring auth. The HeyMCP inspector will show you whether the
    request reached your machine at all.
  </Accordion>

  <Accordion title="Nothing at all in the HeyMCP inspector">
    The request never reached the edge. Check the URL for a typo, and confirm
    `heymcp share` is still running.
  </Accordion>
</AccordionGroup>

## Remove it

```bash theme={null}
claude mcp remove heymcp
```