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

> Custom connectors in the Claude web and desktop app.

<Warning>
  **Do not use `--bearer` with Claude.ai.** The custom connector dialog has no
  field for a static token, so a tunnel that requires one will fail — and
  Claude.ai fails *silently*. Share without it:

  ```bash theme={null}
  heymcp share localhost:8000
  ```
</Warning>

## Add the connector

<Steps>
  <Step title="Open your connectors">
    In Claude, open **Settings**, then **Connectors** under the *Customize*
    heading in the left column.
  </Step>

  <Step title="Add → Add custom connector">
    The **Add** dropdown is at the top right of the connectors panel.

    <Frame caption="Settings → Connectors → Add → Add custom connector">
      <img src="https://mintcdn.com/hey-mcp/im7DhwPBexGDK_h9/images/clients/claude-ai-add-menu.png?fit=max&auto=format&n=im7DhwPBexGDK_h9&q=85&s=f335a295a6cb94a7bd916131b702a8be" alt="The Add dropdown in Claude's connectors panel, showing Browse connectors and Add custom connector" width="744" height="118" data-path="images/clients/claude-ai-add-menu.png" />
    </Frame>
  </Step>

  <Step title="Fill in the dialog">
    | Field                     | What to put                                   |
    | ------------------------- | --------------------------------------------- |
    | **Name**                  | Anything — it's shown in your connectors list |
    | **Remote MCP server URL** | Your full HeyMCP URL, ending in `/mcp`        |

    Leave **Advanced settings** alone. Those two fields are an OAuth Client ID
    and Secret, which a HeyMCP tunnel doesn't use — see
    [Authentication](/security/authentication#oauth).

    <Frame caption="The custom connector dialog, filled in with a HeyMCP tunnel URL">
      <img src="https://mintcdn.com/hey-mcp/im7DhwPBexGDK_h9/images/clients/claude-ai-add-connector.png?fit=max&auto=format&n=im7DhwPBexGDK_h9&q=85&s=9fc25406c33c9b3f420750bcbebc81a0" alt="Claude's Add custom connector dialog with a name and a HeyMCP tunnel URL filled in" width="536" height="596" data-path="images/clients/claude-ai-add-connector.png" />
    </Frame>
  </Step>

  <Step title="Add">
    Claude connects, discovers your tools, and the connector appears in the
    list marked **Custom**.
  </Step>
</Steps>

Watch your HeyMCP inspector while you do this. You should see `INIT`, `NOTIF`
and `LIST` rows appear within a second or two, fingerprinted as Claude.ai.
**If nothing appears, the request never reached your tunnel** and the problem is
the URL, not your server.

## Plan requirements

| Claude plan       | Custom connectors                                                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Free              | One custom connector                                                                                                                 |
| Pro / Max         | Full access                                                                                                                          |
| Team / Enterprise | Owners add them in **Organization settings → Connectors**; members then enable each one individually from **Customize → Connectors** |

On Team and Enterprise, the owner hovers **Custom** and picks **Web** when
adding. Members see the connector labelled "Custom" and click **Connect**.

## Claude reaches you from Anthropic's cloud

The connector is fetched by Anthropic's infrastructure, not by your browser.
Two things follow:

* Your tunnel must be running. A URL that works in your browser because
  something is cached will not work for Claude.
* Claude.ai is not subject to browser CORS on the MCP route.

## Try it

Start a conversation and ask Claude to use one of your tools. The `CALL` row
appears in the inspector as it happens, with the arguments Claude chose.

This is where the classic finding shows up: ask for something with a time in it
and watch Claude send `"7pm"` for a parameter with no `format` constraint.
[`schema/no-format`](/lint#schema-no-format)

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

Claude.ai is the least forgiving client to debug because it says nothing at all.
Work through this in order — it's ordered by how often each one is the answer.

<AccordionGroup>
  <Accordion title="1. Read the handshake report first">
    Before touching Claude, look at the **Handshake** tab in your inspector, or
    run `heymcp probe localhost:8000`.

    Two findings block Claude.ai completely and are invisible from your side:

    * [`transport/content-type`](/lint#transport-content-type) — your MCP route
      answers with something other than `application/json` or
      `text/event-stream`. This is the single most common cause of a connector
      that silently never works.
    * [`transport/accept-sse`](/lint#transport-accept-sse) — your server rejects
      `Accept: text/event-stream`.
  </Accordion>

  <Accordion title="2. Nothing at all in the inspector">
    Claude never reached the edge. Check the URL character by character, confirm
    it ends in `/mcp`, and confirm `heymcp share` is still running in your
    terminal.
  </Accordion>

  <Accordion title="3. INIT arrives but nothing else">
    Your server accepted `initialize` and then something went wrong. Expand the
    `INIT←` row in the inspector to see exactly what it answered. An `OPAQUE`
    row here usually means an HTML error page where JSON was expected.
  </Accordion>

  <Accordion title="4. Tools are listed but never called">
    Claude can see them and is choosing not to use them. Check the handshake
    report for [`tool/no-description`](/lint#tool-no-description) and
    [`tools/description-length`](/lint#tools-description-length) — Claude.ai
    caps descriptions at about 1024 characters and will truncate or drop
    anything longer.
  </Accordion>

  <Accordion title="5. You used --bearer">
    Claude.ai can't send one. Restart the tunnel without it.
  </Accordion>
</AccordionGroup>

<Tip>
  When a tool works in Claude Code and not in Claude.ai, the difference is almost
  always a limit: Claude Code accepts \~8192-character descriptions and
  128-character names, Claude.ai accepts \~1024 and 64.
</Tip>