# Program a cell with an AI agent

> Connect Cursor, Claude Code or another MCP client to a RosieOS cell through the RosieOS MCP server, have the agent author and plan a weld program from a STEP file with offline programming's own engine, and run it on a simulated cell with your confirmation.

URL: https://advancedmetalresearch.com/docs/guides/program-with-an-ai-agent
Section: RosieOS docs / Guides
Last updated: 2026-10-23

This guide connects an AI agent to a simulated cell through the [RosieOS MCP server](https://advancedmetalresearch.com/docs/apis/mcp-server). The agent diagnoses the cell, authors a weld program from a STEP file, plans it, and runs it in simulation once you agree. It edits the same program the [offline programming app](https://advancedmetalresearch.com/docs/guides/offline-programming) shows, with the same rules and refusals, because it runs OLP's own program engine.

Nothing in the first five steps moves a robot. Robot actions are off until you turn them on in step 6, and then only for simulated cells.

## Before you start

- **A simulated cell.** The [quickstart](https://advancedmetalresearch.com/docs/get-started/quickstart) starts rt-core in simulation, the OLP server on `127.0.0.1:8794` and the UI. Keep the UI open beside the agent: it shows the robot, and its STOP works whatever the agent does.
- **The CAD environments**, for STEP import and seam detection. See [Program a weld from CAD](https://advancedmetalresearch.com/docs/guides/offline-programming#before-you-start).
- **The weld planner**, with an NVIDIA GPU, for step 5. Steps 3 and 4 work without it. See [Run the weld planner](https://advancedmetalresearch.com/docs/guides/run-the-weld-planner).
- **Node 20 or later** and an MCP client: Cursor, Claude Code, or any client that starts a stdio server.

## 1. Build the server

From the root of your RosieOS checkout:

```bash
(cd offline-programming/v1/ui && npm ci)
(cd mcp/v1 && npm ci && npm run build)
```

The first command installs the packages of OLP's browser app, which the server bundles so that it runs the same engine.

## 2. Register it with your client

In Cursor, open the RosieOS checkout. Its `.cursor/mcp.json` already registers the server as `rosieos`, with robot actions off. If Cursor lists it as disabled in its MCP settings, enable it there.

For Claude Code:

```bash
claude mcp add rosieos -- node "$PWD/mcp/v1/dist/src/index.js"
```

For any other client, start `node <repo>/mcp/v1/dist/src/index.js` over stdio. The [reference](https://advancedmetalresearch.com/docs/apis/mcp-server#quick-start) has the JSON shape most clients take.

To read rt-core directly as well, set `ROSIE_RT_CONTROL_SOCKET` in the server's `env` to the dev stack's socket, `$ROSIE_LOCAL_RT_DIR/control.sock`. The OLP tools work without it.

## 3. Check the cell

Ask the agent to diagnose the cell, or run the `rosie_diagnose_cell` prompt from your client's prompt menu:

To the agent:

```text
Diagnose the connected RosieOS cell. Don't move anything.
```

The agent reads who controls the robot, OLP's machine status, rt-core's status and events, and planner health, and tells you what state the cell is in. Check that the selected cell says **SIMULATION**. If something is refused or faulted, the agent quotes the code and points to the page that explains it.

## 4. Author a weld program from a STEP file

Run the `rosie_author_weld_program` prompt with the path to a STEP file, or ask in your own words:

To the agent:

```text
Make a new program for /path/to/bracket.step. Put the part on the
positioner table, find the seams, and show me which ones the torch
can reach before you add any welds.
```

The agent creates the program for the cell's robot, imports the part (centred on the work frame, its seams detected), places it, and searches each seam with the fitted torch. Each seam comes back **clear**, **partial** with its clear runs, or **blocked**. You choose which to weld; the agent adds those welds and shows you the spreadsheet.

You can steer it as you would in the app: change the torch or the angle search, set a weld's work angle along the seam, add a stand or a STEP fixture, add a second part, or add taught moves, dwells and Home rows. Every edit goes through OLP's parameter rules, so an out-of-range value is refused in OLP's words, not clamped.

## 5. Plan, preview and save

To the agent:

```text
Plan it. If the planner refuses, tell me which row and why.
Then preview the TCP path and save the program to the cell.
```

`rosie_program_plan` sends the program to the weld planner through OLP. A plan carries the active part's welds; other parts and fixtures go along as obstacles. When it passes, `rosie_program_preview_path` reports the planned tool path per segment without moving anything. `rosie_program_save` writes to the cell's program store, revision-checked, so it never overwrites someone else's newer copy. The program now opens in the browser and on the pendant.

## 6. Run it on the simulated cell

> [!WARNING] **Energised motion on a real cell.** This step allows robot actions on **simulated** cells only. Allowing them on a real cell (`ROSIE_MCP_ROBOT_ACTIONS=cell`) is the cell owner's decision. RosieOS has no software E-stop: keep the hardware E-stop within reach and clear the cell first. See the [safety model](https://advancedmetalresearch.com/docs/get-started/safety-model).

Set `ROSIE_MCP_ROBOT_ACTIONS` to `simulation` in the server's `env` and restart the server from your client. Arm, Load, Play, Run program and the bounded jogs appear, and each refuses unless rt-core describes the selected cell as a simulation.

Then run the `rosie_run_program_in_simulation` prompt, or:

To the agent:

```text
Run the open program on the simulated cell at 10% speed.
```

The agent confirms the target is a simulation and calls `rosie_olp_run_program`. The first call moves nothing: it returns the action (for example *Move to program start and run*) and every joint's move, and the agent shows them to you. Only when you agree does it call again to arm and run. Watch the robot in the OLP UI. Tell the agent to stop at any time, or press STOP in the UI.

While a robot action runs, and for two minutes after it succeeds, the server keeps OLP's heartbeat alive. After that window, OLP's own deadman stops the robot unless the UI or the pendant is keeping the session alive. See [the heartbeat window](https://advancedmetalresearch.com/docs/apis/mcp-server#heartbeat-window).

## When the agent is refused

The server reports refusals in OLP's or rt-core's own words and does not work around them. The common ones:

| Refusal | What it means |
|---|---|
| A robot-action tool is missing | `ROSIE_MCP_ROBOT_ACTIONS` is `off`. Only Stop, Disarm, Pause and Finish cycle exist. |
| *… refused by this MCP server: the selected cell … is backend '…', not a simulation* | The mode is `simulation` and the selected cell is a real robot. Nothing was sent. |
| `target_changed` | Another client selected a different cell between the agent's read and its action. Read status again. |
| `confirmation_stale` | A joint moved more than 0.1° after the agent showed you the confirmation. Ask again. |
| `jog_mode_conflict` | A program is playing or a loop is running, so OLP refuses jogs. |
| `ui_heartbeat_lost` | No client heartbeat reached OLP for 5 s, so it stopped the robot. |

The agent never offers Home, fault reset or recover-to-zero. Those stay with the operator at the cell. Every other code is in [Error codes](https://advancedmetalresearch.com/docs/reference/error-codes) and the [OLP HTTP API](https://advancedmetalresearch.com/docs/apis/olp-http#error-codes).

## Related pages

- [RosieOS MCP server](https://advancedmetalresearch.com/docs/apis/mcp-server): every tool, mode, bound and variable.
- [Program a weld from CAD](https://advancedmetalresearch.com/docs/guides/offline-programming): the same workflow in the browser.
- [Connect to a cell and run a program](https://advancedmetalresearch.com/docs/guides/connect-a-cell): running on a real cell.
- [For AI agents](https://advancedmetalresearch.com/docs/get-started/for-ai-agents): the docs and specs as machine-readable files.

## Sources

Written from these files in the RosieOS repository (https://github.com/advanced-metal-research/RosieOS):

- `mcp/v1/README.md`
- `mcp/v1/src/prompts.ts`
- `mcp/v1/src/config.ts:115-162`
- `mcp/v1/src/tools/robot.ts:70-95,185-205`
- `mcp/v1/src/tools/program.ts`
- `mcp/v1/src/heartbeat.ts`
- `.cursor/mcp.json (RosieOS 04a3435b)`