Guide · AI assistants
Connect Claude, Cursor or ChatGPT to Keel HQ (MCP)
Let an AI assistant read your Keel HQ inventory, cash, ad spend and reports over the Model Context Protocol. Read-only.
Keel HQ runs a Model Context Protocol (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
- 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
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.
Pick your assistant
In AI assistants (MCP), choose the tab for your assistant: Claude Desktop, Claude Code, Cursor or ChatGPT.
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.
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.
In Claude Desktop, open Settings → Developer → Edit Config, add this to claude_desktop_config.json, then restart Claude.
{
"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 installed.
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.
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
- 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
readscope. - 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
| 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. |
Updated October 24, 2026