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
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:
export OPERANDI_API_KEY=ok_live_...
Claude Desktop / Claude Code config
{
"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.