Connect Your AI Assistant to Spall With MCP

MCP, the Model Context Protocol, is the open standard an AI assistant uses to call an outside tool as part of answering a question. Add the @spall/mcp package to Claude Desktop, Cursor, or Copilot and the assistant gets fourteen tools that read your Spall tenant directly, so “which machine is losing us the most money” gets answered from your live data instead of a guess.

Every tool is a read. The package has no tool that creates a rule, edits a work item, or changes anything on a machine. Spall reads from your machines. It never writes to one, and that stays true one hop out through your own assistant too.

Get a read-only key

Open Account → Plan & API → API Keys and create a key. A brand-new key is read-only by default, that covers every tool below except one. If you also want the assistant to ask the factory a question in plain language, check the ask scope box when you create the key. Copy the secret shown, it’s your one chance to see it in full. How to manage API keys and webhooks walks the same screen with screenshots if you need it.

Configure Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "spall": {
      "command": "npx",
      "args": ["-y", "@spall/mcp"],
      "env": {
        "SPALL_API_KEY": "your-read-only-key"
      }
    }
  }
}

Restart Claude Desktop and ask it something about your plant. The install line is npx @spall/mcp, no separate install step.

Configure Cursor

Add the same shape to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "spall": {
      "command": "npx",
      "args": ["-y", "@spall/mcp"],
      "env": {
        "SPALL_API_KEY": "your-read-only-key"
      }
    }
  }
}

Configure Copilot

VS Code’s Copilot reads .vscode/mcp.json:

{
  "servers": {
    "spall": {
      "command": "npx",
      "args": ["-y", "@spall/mcp"],
      "env": {
        "SPALL_API_KEY": "your-read-only-key"
      }
    }
  }
}

Five questions, and the tool each one hits

“What assets do we have on the floor?” hits list_assets, a plain list of the tenant’s assets.

“Which asset is losing us the most money this week?” hits get_opportunities, the same dollar-ranked list the Opportunities page shows, with the rate basis behind each figure.

“What’s the biggest downtime reason on Press 3 this month?” hits get_downtime_pareto, downtime hours ranked by reason for that asset.

“Which machine is most likely to fail in the next week?” hits get_failure_risk, a board priced from each machine’s own mean time between failures, held back for a machine with too few failures to trust the estimate.

“Why was OEE down on nights?” hits ask_factory, the one tool that calls Spall’s own AI and returns the same sourced answer the app’s Ask page gives.

Every tool response carries two parts: a plain-text summary naming its basis, the rate source, a sample count, or “not enough history” when the API has too little behind it, and the raw API data underneath it, unchanged. Ask your assistant to show its sources and it can, because the summary already named them.

What it never does

The package ships fourteen tools and all fourteen are reads. There’s no tool that creates a KPI rule, edits a work order, acknowledges an alert, or writes a setpoint. An assistant connected through this package can tell you what’s happening on your floor. It can’t change anything on it.

The ask scope and budget

Thirteen of the fourteen tools need nothing beyond a valid key, the same reads the rest of the public API exposes. ask_factory is different: it calls Spall’s own AI, so it needs a key with the ask scope specifically, opt in when you create the key, and it draws against a daily question budget set on your account. Once that budget is spent for the day, the tool returns a plain message naming that instead of an error, and the budget resets the next day. Every other tool runs under your key’s normal rate limit, no separate budget to track.

Quick recap

• MCP lets Claude Desktop, Cursor, or Copilot call Spall’s public API directly, through npx @spall/mcp and a key pasted into your client’s own config.
• Get a read-only key from Account → Plan & API → API Keys. Add the ask scope only if you want the assistant to ask the factory a question.
• All fourteen tools are reads. None of them create, edit, or delete anything in Spall or on a machine.
• Every tool answer names its basis and returns the raw API data alongside the summary, so a cited figure can always be checked.
• ask_factory alone needs the ask scope and draws against a daily question budget, with a plain message when it is spent for the day.