# Connect Claude, Cursor or ChatGPT to Keel HQ (MCP) (/guides/connect-ai-assistants)

Keel HQ runs a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server. Connect an AI assistant to it and you can ask questions such as "Which products run out in the next 30 days?" or "What's my cash runway?", and the assistant answers from your Keel HQ data.

The connection is **read-only**: an assistant can read your data but can't change anything in Keel HQ or your store.

## What you need [#what-you-need]

- A Keel HQ **admin** account, to create the token. If you're not an admin, ask one for a read-only token.
- One of: Claude Desktop, Claude Code, Cursor or ChatGPT.

## Connect an assistant [#connect-an-assistant]

Everything happens on one screen: **Settings → API Tokens**, in the **AI assistants (MCP)** section. It shows the server URL, a tab for each assistant with its exact config, and a connection test.

<Steps>
<Step>

### Pick your assistant [#pick-your-assistant]

In **AI assistants (MCP)**, choose the tab for your assistant: **Claude Desktop**, **Claude Code**, **Cursor** or **ChatGPT**.

</Step>
<Step>

### Create a read-only token [#create-a-read-only-token]

Choose **Create token for _your assistant_**. Keel HQ creates a read-only token that expires in 90 days and fills it into the config below.

Copy the token now. It's shown only once: after you leave the page, Keel HQ can't show it again.

Create a separate token for each assistant, so you can revoke one without breaking the others.

</Step>
<Step>

### Add Keel HQ to your assistant [#add-keel-hq-to-your-assistant]

Copy the config from the tab and add it to your assistant. The tab shows your real server URL and token; the examples below use placeholders.

<Tabs items={['Claude Desktop', 'Claude Code', 'Cursor', 'ChatGPT']}>
<Tab value="Claude Desktop">

In Claude Desktop, open **Settings → Developer → Edit Config**, add this to `claude_desktop_config.json`, then restart Claude.

```json title="claude_desktop_config.json"
{
  "mcpServers": {
    "keel": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.keelhq.io/api/mcp", "--header", "Authorization:${KEEL_AUTH}"],
      "env": {
        "KEEL_AUTH": "Bearer eos_YOUR_TOKEN"
      }
    }
  }
}
```

Claude Desktop connects through the `mcp-remote` bridge, which runs with `npx`, so it needs [Node.js](https://nodejs.org) installed.

</Tab>
<Tab value="Claude Code">

Run this in a terminal:

```bash
claude mcp add --transport http keel https://app.keelhq.io/api/mcp --header "Authorization: Bearer eos_YOUR_TOKEN"
```

Add `--scope user` to make Keel HQ available in every project.

</Tab>
<Tab value="Cursor">

Add this to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a project:

```json title="mcp.json"
{
  "mcpServers": {
    "keel": {
      "url": "https://app.keelhq.io/api/mcp",
      "headers": {
        "Authorization": "Bearer eos_YOUR_TOKEN"
      }
    }
  }
}
```

</Tab>
<Tab value="ChatGPT">

1. In ChatGPT, open **Settings → Apps & Connectors → Advanced settings** and turn on **Developer mode**.
2. Create a connector with the server URL `https://app.keelhq.io/api/mcp`.
3. For authentication, pick the API key or bearer token option and paste your token.

ChatGPT offers the token option only on some plans. If you see only OAuth and No authentication, ChatGPT can't connect yet: Keel HQ signs in with tokens, not OAuth.

</Tab>
</Tabs>

</Step>
<Step>

### Test the connection [#test-the-connection]

Back in **AI assistants (MCP)**, paste the token under **Test connection** and choose **Test connection**. Keel HQ checks the token against the same server URL your assistant uses and lists the tools the assistant will see.

</Step>
</Steps>

## What an assistant can read [#what-an-assistant-can-read]

| Tool | What it returns |
| --- | --- |
| `get_overview` | Month-to-date vitals, alerts, trends, inventory health and recent activity. |
| `get_cash_dashboard` | Cash balances, debts, upcoming bills, expected income, runway and cash alerts. |
| `list_inventory_products` | A page of your active products (up to 200 at a time). |
| `get_inventory_product` | Every active product with a given SKU, with its days of cover. |
| `get_ads_spend` | Meta Ads spend by campaign and calendar month, up to 12 months at a time. |
| `get_monthly_report` | A published monthly report, with notes on any figures that were held back. |
| `get_brand_settings` | Your brand profile: name, voice, colors, fonts, targets and alert thresholds. No secrets. |

The assistant can also read how Keel HQ defines each metric.

**How fresh the figures are.** Every answer starts with when each source last synced and whether it's fresh, stale, never synced or failed. Assistants are told to mention it when a figure is out of date.

**Missing data stays missing.** When Keel HQ can't work out a figure, the assistant gets "unknown" with a reason, never a 0.

**Reports.** Only **published** monthly reports are readable. Drafts and archived reports aren't.

## Security [#security]

- **Your organization only.** A token belongs to the organization it was created in. An assistant using it sees that organization's data and nothing else.
- **Read-only.** The tools only read data. A token created here has only the `read` scope.
- **Revocable.** Revoke a token in **Settings → API Tokens → Tokens** and it stops working immediately.
- **Expires.** Tokens created for an assistant expire after 90 days. When you create a token from **Tokens** with **Create token**, you can pick 30, 90 or 365 days, or no expiry.
- **Rate-limited.** Each token can make 120 requests a minute.
- **Tied to its creator.** A token stops working if the admin who created it leaves the organization, stops being an admin, or has their access limited to some modules. It works again if their access is restored.
- **At most three active tokens** per organization. Revoke an old one to free a slot.

## Troubleshooting [#troubleshooting]

| What you see | What it means | What to do |
| --- | --- | --- |
| "The token isn't valid. It may be revoked or expired." | The token is wrong, revoked or past its expiry. | Create a new token and update your assistant's config. |
| 'The token lacks the "read" scope.' | The token was created without read access. | Create a read-only token from **AI assistants (MCP)**. |
| "Too many requests with this token." | The token went over 120 requests in a minute. | Wait a minute and try again. |
| The token shows **Inactive** in **Tokens**. | Its creator is no longer an admin, has limited access, or has left. | Revoke it and create a new one as a current admin. |
| Claude Desktop doesn't show Keel HQ. | The config didn't load, or Node.js isn't installed. | Check the JSON is valid, install Node.js, then restart Claude Desktop. |
| ChatGPT offers only OAuth or No authentication. | Your ChatGPT plan doesn't offer token sign-in. | Use Claude Desktop, Claude Code or Cursor for now. |
| An answer says a source is stale. | That integration hasn't synced on schedule. | Check the integration in **Settings → Integrations**. |