# Keel HQ for agents (/agents)
These docs are built to be read by AI agents as well as people.
## Read the docs as Markdown [#read-the-docs-as-markdown]
- **Every page as Markdown:** add `.md` to a page's URL, for example [`/quick-start.md`](/quick-start.md). The home page is [`/index.md`](/index.md).
- **An index of every page:** [`/llms.txt`](/llms.txt), following the [llms.txt convention](https://llmstxt.org).
- **The whole site in one file:** [`/llms-full.txt`](/llms-full.txt).
- **From a page:** **Copy Markdown** copies the page, and the menu next to it opens the page in ChatGPT, Claude or another assistant.
## Read a brand's data [#read-a-brands-data]
Keel HQ has a read-only MCP server for a brand's own inventory, cash, ad spend and published reports. It needs an API token from the brand's workspace. See [Connect Claude, Cursor or ChatGPT](/guides/connect-ai-assistants).
## Name [#name]
The product is **Keel HQ**. Another company sells inventory software as "Keel", so write the name in full.
# Connect your bank (/connect/bank)
For now, connect Mercury from **Settings → Integrations**.
## Outline [#outline]
- **Mercury:** connect it in **Settings → Integrations** and see which accounts and transactions Keel HQ reads.
- **What it powers:** cash balances, runway and the cash forecast.
- **How often it syncs.**
- **Other banks:** what's supported today.
- **Disconnecting:** what happens to synced data.
- **Troubleshooting:** a failed sync or an unreadable credential.
# Connect Shopify (/connect/shopify)
The [quick start](/quick-start) covers connecting Shopify and running the first syncs.
## Outline [#outline]
- **Install:** from the Shopify App Store, or connect from **Settings → Integrations**.
- **What Keel HQ syncs:** products and variants, inventory, orders and refunds, and how often.
- **First syncs:** the first product sync and first order sync, and how long they take.
- **Locations:** how inventory is counted across your locations.
- **Two storefronts:** connecting a DTC store and a B2B store.
- **Disconnecting or uninstalling:** what happens to synced data.
- **Troubleshooting:** a sync error, or figures that don't match Shopify.
# FAQ (/faq)
## Are Blended ROAS and MER the same thing? [#are-blended-roas-and-mer-the-same-thing]
Yes when you have no costs in the **Agency Fees** category. Otherwise, MER includes those costs as well as ad spend, so it is lower than Blended ROAS.
```
Net Revenue = DTC + B2B line items after discounts + shipping − refunds
Blended ROAS = Net Revenue / total ad spend (all ad channels; Meta Ads today)
MER = Net Revenue / total marketing spend (ad spend + non-media marketing costs)
```
- Today, non-media marketing costs are costs in **Settings → Costs** in the **Agency Fees** category. They are normalized for the selected window before Keel HQ includes them in MER.
- People use these names differently online, and some use gross rather than net revenue. Keel HQ uses the same net revenue for both, so they are directly comparable.
- Unknown ad spend makes both metrics **—**. With known $0 ad spend, Blended ROAS is **—** and MER uses the marketing costs alone.
- Set **Target ROAS** in **Settings → Goals**. Set the **MER target** in **Settings → Goals → Ad Targets**, or in **Ads Settings**.
- Meta ROAS is a third metric: Meta's attributed purchase value divided by Meta spend. The Overview does not show it yet; the Ads account snapshot shows 7- and 14-day figures.
# Keel HQ Docs (/)
Keel HQ brings a Shopify brand's inventory, cash, margins and marketing into one place. These docs cover how to set it up, how each part works, and how to connect an AI assistant to your data.
Get an account, connect Shopify and finish the setup checklist.
Let an AI assistant read your Keel HQ data over MCP.
One guide per job, filtered by topic.
Markdown copies of every page, `llms.txt`, and where the MCP server is.
## Need a hand? [#need-a-hand]
Choose **Help** in the Keel HQ sidebar to message us, or **Report a bug** to tell us something is broken.
# Modules (/modules)
Each module gets its own page. This list follows the Keel HQ sidebar.
## Outline [#outline]
- **Overview:** month-to-date vitals, alerts and trends.
- **Cash:** balances, debts, cash flow and the forecast.
- **Inventory:** catalog, purchase orders, margins, returns and reorder actions.
- **Marketing:** calendar, posts, email and SMS.
- **Ads** (beta): Meta Ads performance.
- **Warehouse.**
- **Journal.**
- **Reports** (beta): monthly reports.
- **The Helm** (beta).
# Quick start (/quick-start)
Keel HQ reads your store's products and orders from Shopify, then adds your costs so it can work out margins and cash. The setup checklist has four required steps; the rest are recommended.
## Before you start [#before-you-start]
- A Shopify store you can install apps on.
- Your fixed monthly costs (rent, salaries, software), so Keel HQ can work out your margins.
## Set up Keel HQ [#set-up-keel-hq]
### Get an account [#get-an-account]
Keel HQ is in private beta. New accounts are created while connecting a Shopify store, or by invitation from someone already on Keel HQ.
If you already have an account, sign in at [app.keelhq.io](https://app.keelhq.io/login).
### Open the setup checklist [#open-the-setup-checklist]
Choose **Get started** in the sidebar. The checklist shows how many required steps are done, and each step links to the screen where you finish it.
### Connect Shopify [#connect-shopify]
Go to **Settings → Integrations** and connect your store under **Shopify**. See [Connect Shopify](/connect/shopify) for what Keel HQ syncs.
### Run the first product and order syncs [#run-the-first-product-and-order-syncs]
Still in **Settings → Integrations**, under **Shopify**, run the first product sync and then the first order sync. The checklist ticks each one off when it finishes.
### Add your fixed costs [#add-your-fixed-costs]
Go to **Settings → Costs** and add your fixed costs. Keel HQ needs them for profit and cash figures.
That's the required setup. The checklist then lists the recommended steps.
## Recommended next steps [#recommended-next-steps]
| Step | Where |
| --- | --- |
| Connect Mercury, your bank | **Settings → Integrations** (see [Connect your bank](/connect/bank)) |
| Connect ShipStation, Meta Ads, Klaviyo or Postscript | **Settings → Integrations** |
| Add variable costs | **Settings → Costs** |
| Set revenue goals | **Settings → Goals** |
| Invite a team member | **Settings → Team** |
You can skip a recommended step from the checklist. Viewers see the checklist's progress but can't complete or skip steps.
## What's next [#whats-next]
- [Connect Claude, Cursor or ChatGPT](/guides/connect-ai-assistants) to ask questions about your data in an AI assistant.
- Browse the [guides](/guides) for one job at a time.
# API tokens (/reference/api-tokens)
For now, [Connect Claude, Cursor or ChatGPT](/guides/connect-ai-assistants) covers creating a read-only token.
## Outline [#outline]
- **What a token is:** a bearer token, scoped to one organization, shown once at creation.
- **Create a token:** Settings → API Tokens → **Create token**: name, expiry (30, 90 or 365 days, or never) and access (read-only or read and write). Admins only.
- **Copy it once:** the one-time reveal, and what to do if you lose it.
- **Token status:** Active, Expired, Revoked and Inactive, and why a token goes inactive.
- **Limits:** three active tokens per organization; rotating without downtime.
- **Revoke a token.**
- **Use a token:** the `Authorization: Bearer` header.
# 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.
### Pick your assistant [#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 [#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 [#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.
```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.
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.
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"
}
}
}
}
```
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.
### 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.
## 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**. |