OPERANDI MCP Server — operate real appliances from any agent

mcp-name: cc.operandi/operandi

operandi_mcp_server.py exposes OPERANDI over the Model Context Protocol so any MCP-capable agent host (Claude Desktop, Claude Code, or your own agent runtime) can identify an appliance and pull its grounded, safety-checked, robot-executable operation package as native tools.

This is the "build for agents" surface: the customer is a robot's planner / an LLM agent, not a human reading PDFs.

Tools

Tool	What it does
`identify_appliance`	Resolve observed nameplate text / panel labels / model → a catalog object (call first).
`get_operation_package`	The robot-executable package: model-exact procedures, control map + grounding, per-step verification signals, recovery state machine, safety envelope.
`list_appliances`	Browse operable appliances (optionally by category).
`find_by_capability`	Find appliances by function (`heat` / `wash` / `brew` / `defrost` …).

Why an agent wants this

A general model, cold, gives confidently-wrong physical instructions on ordinary appliances a large fraction of the time (OPERANDI Stage A: 24% of cold instructions were would-fail, including invented buttons and cycles). Grounded in the package these tools return, that fell to 0 hallucinations, 96% exact. The tools turn "guess the buttons" into "read the manufacturer's ground truth". See ../docs/BUSINESS_MODEL.md.

Setup — zero config

Terminal

pip install operandi-mcp

That's it. No key needed for your first packages: on first use the server mints an instant trial key itself (POST /v1/trial — no signup, 2 operation packages included, cached at ~/.operandi/mcp_key). When the trial is spent, tool responses tell the agent exactly how to sign up free (10 packages/month) or go Pro.

Have a key already? Set it and it wins over the trial:

server.ts

export OPERANDI_API_KEY=ok_live_...

Claude Desktop / Claude Code config

config.json

{
  "mcpServers": {
    "operandi": { "command": "operandi-mcp" }
  }
}

(Optionally add "env": {"OPERANDI_API_KEY": "ok_live_..."} once you have an account key.)

Then ask the agent: "Identify the Samsung ME20H705MSS and give me the safe procedure to defrost 0.5 kg of mince." — it will call identify_appliance then get_operation_package and answer from grounded data.

Notes

The server is a thin, API-key-authenticated REST client — the same binary works against local dev or the hosted service by changing OPERANDI_API_URL.
Auth is Authorization: Bearer <key>; a missing/invalid key surfaces as a tool error, not a crash.
Transport is newline-delimited JSON-RPC 2.0 (the MCP stdio transport). Offline protocol tests: pytest tests/test_mcp_server.py.