upan-mcp

upan-mcp is an open-source Model Context Protocol server that runs on your PC and connects an AI agent — Claude Code, Claude Desktop, Cursor or another MCP client — to your UPAN. It talks to the device locally, over USB-C or over your local network, with no cloud in between. The agent works around the device, not inside it: it reads the state and limits, writes motion programs and sends commands, and the motion MCU checks every one of them before anything moves.

Warning: upan-mcp is in development and not released yet. The install command, tool names and options on this page may change.

Install

The intended one-line install for Claude Code:

claude mcp add upan -- uvx upan-mcp

This command may change before the release. Configuration snippets for other MCP clients (Claude Desktop, Cursor) are planned and not final yet.

How it connects

AI agent  ──MCP──▶  upan-mcp (your PC)  ──USB-C──────────▶  UPAN Core
                                         └──local network──▶  (network API)

• Over USB-C it uses the same binary protocol as upan-cli. See USB protocol.
• Over the network it uses the device's local API and logs in with the device password; see Network API. The password is not sent over the network.
• With a multi-axis stack, it talks only to the UPAN Core; the Core coordinates the UPAN Axis modules.

The package is built on the same Python host library as upan-cli.

What an agent can do

• Read device information, state, position, inputs, outputs and both layers of limits — so it knows the machine before planning a move.
• Move: relative and absolute moves, jogging, homing, stop, and synchronised straight-line moves across a module stack.
• Write programs: turn "feed 300 mm, wait for the pedal, return, repeat 50 times" into a program, upload it and run it. The device checks the whole program before the first step and answers with the exact instruction and allowed value if something is out of range.
• Change working limits (SoftConfig) inside the machine limits.
• Switch outputs and wait for inputs.
• Install apps on the device (planned; see Web apps).

Units

The protocol knows only integer micrometres and millidegrees. upan-mcp accepts millimetres or inches from the agent and converts exactly (1 in = 25.4 mm) in code. The agent does not do unit arithmetic itself.

When the device refuses

A refusal includes the reason and the nearest allowed value, for example "travel max — requested 120 mm, allowed 100 mm", or "program instruction #7 — velocity too high, allowed 50 mm/s". The agent can correct its request from the answer without guessing. See ErrorCode and LimitViolation.

What an agent cannot do

• Change machine limits. HardConfig — travel, maximum speed and acceleration, motor current, limit switch settings — can be changed only over USB and only within 30 s after a person presses the button on the device. See Configuration.
• Bypass limits. Every command and every program step is checked by the motion MCU against the limits stored on the device. The worst result of a bad request is a refusal.
• Override the stop input. It is a hardware circuit and works without any software. See Safety.
• Take control from someone silently. Over the network only one client controls the axis at a time; taking over is explicit and the previous controller is notified. stop is accepted from anyone.

Note: You stay responsible for setting realistic machine limits for your mechanics. The device enforces the limits you set; it cannot know the limits you did not set.

Without hardware

You can try commands and programs against the simulator, which runs the real motion firmware core on your PC; see USB protocol. Whether upan-mcp will connect to the simulator directly is not final yet.