---
title: "Connect AI Tools (MCP)"
description: "Connect Claude, Cursor, or any MCP client to your SpireStock workspace. Read-only, scoped to one workspace, revocable at any time."
source: https://0.0.0.0:3006/docs/mcp
---

# Connect AI Tools (MCP)

Let Claude, Cursor, or any MCP-compatible assistant read your SpireStock workspace, so you can ask questions in plain language instead of building a report for each one.

`@spirestock/mcp-server` is a [Model Context Protocol](https://modelcontextprotocol.io) server. Your AI tool runs it locally, it authenticates with a workspace API key you issue yourself, and it exposes eight read-only tools the assistant can call while answering you.

💡 

Read-only

This connection can look at your data. It cannot place orders, edit records, change settings, manage API keys, or touch billing. Those route groups are unreachable with an API key regardless of scope.

## Setup

### 1\. Create a connection key

In the SpireStock dashboard, open **Developer → AI Tools** and choose **Generate connection key**. This issues a read-only API key scoped to your workspace, valid for one year.

The key is shown once — only a hash is stored, so it cannot be retrieved later. It looks like `df_` followed by 64 characters.

### 2a. Claude Code

Run this in your terminal:

Terminal 

```bash
claude mcp add --env SPIRESTOCK_API_KEY=df_your_key_here --transport stdio spirestock -- npx -y @spirestock/mcp-server
```

### 2b. Claude Desktop, Cursor, and other clients

Add the server to the app’s MCP configuration file, then restart it:

MCP configuration 

```json
{
  "mcpServers": {
    "spirestock": {
      "command": "npx",
      "args": ["-y", "@spirestock/mcp-server"],
      "env": {
        "SPIRESTOCK_API_KEY": "df_your_key_here"
      }
    }
  }
}
```

### 3\. Check it works

Ask your assistant something only your workspace could answer — “what were yesterday’s orders?” or “which SKU sold best last week?” If it answers with real figures, the connection is live.

## Available tools

| Tool | What it reads |
| --- | --- |
| `list_orders` | Orders, filtered by date range, status, town, route, or a search over order code and customer name. |
| `get_order` | One order with its line items. |
| `list_accounts` | Customers and retailers, with name search. |
| `get_account` | One account, plus its outstanding ledger balance. |
| `list_products` | The SKU catalogue, with pricing and packaging. |
| `run_report` | Any of 34 built-in reports — sales, SKU sales, attendance, expenses, distributor activity, beat productivity. |
| `dashboard_summary` | Headline KPIs, monthly sales trend, recent orders, activity feed, crate balances. |
| `list_masters` | Reference data — territories, routes, towns, brands, product classes, rate cards, shifts. |

`run_report` and `list_masters` take a slug rather than being split into one tool each. That keeps 89 endpoints from crowding out the rest of the list — an assistant given a hundred near-identical tools picks badly between them.

## Configuration

| Variable | Default | Meaning |
| --- | --- | --- |
| `SPIRESTOCK_API_KEY` | required | Your workspace connection key. |
| `SPIRESTOCK_API_URL` | `https://api.spirestock.com` | API host. Must be HTTPS unless it is localhost. |
| `SPIRESTOCK_TIMEOUT_MS` | `30000` | Per-request timeout. Raise it for very large reports. |

## Security

-   **Scoped to one workspace.** The key carries its organization, and every request runs inside that tenant scope. It cannot read another organization’s data.
-   **Read-only.** Issued with the `read` scope, so writes are refused by the API as well as being absent from the package.
-   **Cannot manage itself.** API keys can never reach the developer, billing, auth, or admin route groups, so a leaked key cannot mint more keys, repoint a webhook, or start a purchase.
-   **Revocable.** Delete the key under **Developer → API Keys** and it stops working immediately.
-   **Separately rate-limited.** Each key gets its own bucket, so a busy assistant will not rate-limit you out of the dashboard.
-   **Plan-aware.** On a paid plan, reads keep working even through a billing lapse — a failed card retry never breaks your integrations. On the free trial, API and AI-tool access ends with the trial and resumes on upgrade; your data stays viewable and exportable from the dashboard throughout.

⚠️ 

Where your data goes

When you connect this server, the AI tool you are using reads your workspace data and sends it to whichever AI provider that tool runs on. That is your tool and your provider relationship, not SpireStock’s — but it is worth being deliberate about, particularly for customer, pricing, and margin data. Check your organisation’s policy before connecting.

Your key is also stored in a config file in plaintext, as with any CLI credential. Treat it like a password: do not commit it, and revoke it if the machine is shared or lost.

## Troubleshooting

### “SPIRESTOCK\_API\_KEY is not set”

The variable did not reach the process. In Claude Desktop and Cursor it belongs in the `env` block of the MCP config, not your shell profile — those apps do not inherit your terminal environment.

### “SpireStock rejected the API key”

The key was revoked or has expired. Issue a new one from **Developer → AI Tools**.

### “API key is not scoped for /reports”

The key was created with narrower scopes than the tool needs. Keys made through the AI Tools tab always carry `read`; a key created by hand may not.

### It answered about today when I asked about last month

The orders endpoint returns today’s orders when no date range is given, so the assistant may have fetched a single day. The tool flags this in its output; if it happens, state the date range explicitly.

### A report timed out

Large reports can exceed the 30-second default. Narrow the date range, or raise `SPIRESTOCK_TIMEOUT_MS`.

## Frequently asked questions

▸ What does the MCP server let an assistant do?

It exposes eight read-only tools scoped to your workspace: list and inspect orders, list and inspect accounts with their ledger balance, browse the product catalogue, run any of 34 built-in reports, read dashboard KPIs, and read master data such as territories, routes and rate cards. The assistant can look at all of it and answer questions about it. It cannot place an order, edit a record, change settings, manage API keys, or touch billing.

▸ Why is it read-only?

An API key acts with workspace-admin authority inside its organisation. An assistant mis-firing a write against live order data is a different risk from an ERP sync doing it deliberately, so writes are left out entirely rather than guarded. If you need machine writes today, issue a normal API key with a write scope and call the REST API directly — that path is deliberate, auditable, and something a person configured.

▸ Do I need a separate credential?

No. There is no OAuth flow and no consent screen. Authentication is the X-API-Key header — the same key the REST API and any other integration uses. Generate one under Developer → AI Tools in the dashboard, and revoke it in the same place.

▸ Can it read another organisation's data?

No, and not by policy alone. A key carries its organisation, and every route it can reach runs inside a tenant scope that filters each query to that organisation. Route groups that would escape it — auth, developer, billing, platform, super-admin, portal, driver-app and support — refuse API keys outright regardless of scope, so a key cannot mint more keys, repoint a webhook, or start a purchase either.

▸ Where does my data actually go?

Your AI tool reads workspace data through this server and sends it on to whichever AI provider that tool runs on — Anthropic for Claude, whoever Cursor is configured against, and so on. That is your tool and your provider relationship, not SpireStock's. It is worth checking against your organisation's policy before connecting customer, pricing or margin data.

▸ How do I revoke access?

Delete the key under Developer → API Keys. It stops working immediately — keys are checked against the database on every request, so there is no cached session to expire. Keys generated from the AI Tools tab appear in that list like any other.

▸ Does it keep working if my trial ends?

On a paid plan, yes — a billing hiccup never breaks reads, so a failed card retry cannot take your integrations down. On the free trial, API and AI-tool access ends with the trial: connections pause until you upgrade, and the assistant is told exactly that. Your data stays safe either way, and you can always view and export everything from the dashboard.

▸ Will an assistant flood my API or run up a bill?

Each key gets its own rate-limit bucket, so a busy assistant cannot rate-limit you out of the dashboard. Responses are also capped and trimmed before they reach the model — 50 rows by default, 200 maximum, with a note saying how many of the total you are seeing. There is no per-call charge from SpireStock for using this; any model cost is between you and your AI provider.

▸ Which clients does it work with?

Any MCP client that can launch a local stdio server. Claude Code, Claude Desktop and Cursor are the ones we document and test. The server runs on your machine via npx and talks to the SpireStock API over HTTPS; there is no remote MCP endpoint to allowlist.

▸ Is this different from the AI assistant already in the app?

Yes. The in-app assistant is SpireStock AI answering inside the dashboard. The MCP server is the opposite direction: it lets the AI tool you already use reach into your workspace, so you can ask about your data in the same place you are already working.

## Next steps

-   [API keys and scopes](/docs/getting-started#api-keys) — how keys authenticate and what they can reach.
-   [API reference](/api-reference) — the endpoints behind these tools, if you would rather call them directly.
-   [Webhooks](/docs/webhooks) — for pushing events out to your systems instead of pulling data in.