Connect any MCP client or AI agent to Keel HQ

If you build your own agent, or use a tool that speaks the Model Context Protocol and isn't one of the named clients, this is the page. Keel HQ exposes one HTTP endpoint and a bearer token, and what comes back is the same data the named clients get.

What your agent can read

Keel HQ serves a read-only Model Context Protocol server. These are the tools it exposes:

Two resources come with it: eos://docs/metric-calculations, which defines how each figure is calculated, and eos://reports/monthly/{year}-{month}, a published report as markdown.

These tools read your Shopify orders and products, Meta Ads campaign spend, Mercury balances and published monthly reports, all from what Keel HQ has already synced. There is no tool for Klaviyo or Google Ads data on its own.

Questions it can answer

• "How many days of cover does one of my SKUs have, and which products share that SKU across my stores?"

• "What's my cash runway, and which bills are coming up?"

• "Show Meta spend by campaign for the last three months. Was any month only partly synced?"

• "Summarize last month's published report, and tell me which figures were withheld and why."

• "Is everything you just told me current? Check the data freshness."

The questions that pay off are the ones across sources: inventory against cash, spend against revenue. Keel HQ has already joined them, and your assistant just reads the result.

Connect your agent

1. 01Create a token

   In Keel HQ, open Settings → MCP & API tokens, and find AI assistants (MCP). Click to create a token for your agent. It carries the read scope and expires in 90 days by default. It's shown once, so copy it before you leave the page.

2. 02Call the endpoint

   Send JSON-RPC over POST to the Keel HQ URL ending in /api/mcp, with Authorization: Bearer eos_…. With your token in KEEL_TOKEN, list the tools:

   curl -X POST https://app.keelhq.io/api/mcp \
     -H "Authorization: Bearer $KEEL_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
   

   The server is stateless: there is no session to open or close.

3. 03Test the connection

   Back in Settings → MCP & API tokens, Test connection runs the same tools/list call an assistant makes and shows the tool names it got back. Then ask a question.

Tokens, scopes and revoking

• Scope. MCP needs a token with the read scope. A token without it gets a 403, and a missing or revoked one gets a 401.

• Expiry. 30, 90 or 365 days when you create it; 90 by default.

• Revoking. Revoke the token in Settings → MCP & API tokens. The assistant loses access immediately.

• Rate limit. 120 requests a minute per token.

Your organization comes from the token, never from the request, so an assistant can only see the workspace the token was created in.

Known limits

• Read-only, by design. your agent can't update products, record costs or send anything.

• Data is as fresh as the last sync. Shopify orders sync every six hours, so a very recent sale may not be there, and each result says so in data_freshness.

• Ad spend is by calendar month and limited to a 12-month range. There is no daily breakdown.

• Only Claude, ChatGPT and Cursor have been tested. Other clients may work, and aren't supported by name.

• Keel HQ is in private beta, with a waitlist.