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

# Which client, and what to expect

> A compatibility matrix, and the one thing that will waste your afternoon if you don't know it.

Every guide here assumes you already have a URL from `heymcp share`. If you
don't, start with the [quickstart](/quickstart).

## Start with Claude Code

It is the most permissive of the clients, it's the only one where adding a
connector is a single command, and — crucially — **it tells you when something
goes wrong**. Get your server working there first, then move to the clients that
fail quietly.

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

## The matrix

|                           | Claude Code         | Claude.ai             | ChatGPT            | Grok        | Cursor             | VS Code            | Gemini          |
| ------------------------- | ------------------- | --------------------- | ------------------ | ----------- | ------------------ | ------------------ | --------------- |
| Where you configure it    | CLI                 | Settings → Connectors | Settings → Plugins | Web UI      | `.cursor/mcp.json` | `.vscode/mcp.json` | `settings.json` |
| Can send a static bearer  | **Yes**             | **No**                | **No**             | Check in UI | **Yes**            | **Yes**            | **Yes**         |
| Works with `--bearer`     | Yes                 | **No**                | **No**             | Maybe       | Yes                | Yes                | Yes             |
| Failure mode when unhappy | Error in transcript | **Silent**            | Error toast        | Error in UI | Error in panel     | Error in panel     | Error in CLI    |
| Tool description limit    | \~8192 chars        | \~1024 chars          | \~1024 chars       | —           | —                  | —                  | —               |
| Tool name limit           | 128 chars           | 64 chars              | 64 chars           | —           | —                  | —                  | —               |

<Warning>
  **Neither Claude.ai nor ChatGPT can send a static bearer token.** Their dialogs
  offer OAuth credentials or nothing — there is no header field. Share without
  `--bearer` for either of them.

  With Claude.ai this matters more than it sounds: it will fail *silently*, with
  nothing in the UI to tell you why.
</Warning>

## Protocol revisions

| Client      | Negotiates              |
| ----------- | ----------------------- |
| Claude.ai   | 2024-11-05 → 2026-07-28 |
| ChatGPT     | 2025-03-26 → 2025-06-18 |
| Claude Code | 2024-11-05 → 2025-06-18 |

If your server negotiates a revision one of these can't speak, the
[probe warns you](/lint#mcp-protocol-version) by name before that client ever
tries.

## The silent-failure problem

This is the reason HeyMCP exists, so it's worth stating plainly.

When Claude.ai can't use your MCP server, it does not say so. The connector
just doesn't appear, or appears and never calls anything. There is no error in
the UI, nothing in the browser console, and frequently nothing in your own
server logs either — because the request that failed never reached your code.

The two most common causes are both invisible from your side:

* Your MCP route answers with a content-type other than `application/json` or
  `text/event-stream`. [`transport/content-type`](/lint#transport-content-type)
* Your server rejects `Accept: text/event-stream`.
  [`transport/accept-sse`](/lint#transport-accept-sse)

The handshake probe catches both before you ever open a client. If a connector
isn't behaving, **read the handshake report first** — it is faster than any
amount of clicking.

## Pick your client

<CardGroup cols={2}>
  <Card title="Claude Code" icon="terminal" href="/clients/claude-code">
    One command. Start here.
  </Card>

  <Card title="Claude.ai" icon="message" href="/clients/claude-ai">
    Custom connectors in the web app.
  </Card>

  <Card title="ChatGPT" icon="message" href="/clients/chatgpt">
    Needs Developer mode switched on.
  </Card>

  <Card title="Grok" icon="message" href="/clients/grok">
    grok.com/connectors → Custom.
  </Card>

  <Card title="Cursor" icon="code" href="/clients/cursor">
    A `mcp.json` entry.
  </Card>

  <Card title="VS Code" icon="code" href="/clients/vscode">
    Copilot's MCP configuration.
  </Card>

  <Card title="Gemini" icon="terminal" href="/clients/gemini">
    Gemini CLI's `settings.json`.
  </Card>
</CardGroup>