# upan-mcp

> The open-source MCP server that lets an AI agent on your PC read and control UPAN locally — status, planned install command and what an agent can and cannot do.

`upan-mcp` is an open-source [Model Context Protocol](https://modelcontextprotocol.io) 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:

```powershell
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

```text
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](/docs/usb-protocol).
- **Over the network** it uses the device's local API and logs in with the device password; see [Network API](/docs/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](/docs/programs), 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](/docs/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`](/docs/api#ErrorCode) and [`LimitViolation`](/docs/api#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](/docs/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](/docs/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](/docs/usb-protocol#simulator). Whether `upan-mcp` will connect to the simulator directly is not final yet.