Connect an Agent over MCP
Let an Agent observe the robot, run tasks, calibrate and perform manual motion.
After installation, an MCP-compatible Agent can connect to local RoboAPI and share devices and settings with the console. This page lists the 27 tools provided in 0.4.5.
Connect an Agent
Start the local console and network MCP together:
roboapi http --with-mcpThe default MCP address is http://127.0.0.1:8000/mcp; the console is http://127.0.0.1:8080/. Forward both ports to access them from another computer. Do not start another process using the same hardware.
A stdio client on the control computer can use this configuration. Replace command with the absolute path in the installation environment:
{"mcpServers":{"roboapi":{"command":"/absolute/path/to/.venv/bin/roboapi","args":["serve"]}}}serve also starts the console on port 8080 by default. Configuration belongs to the account running the process. Stop the existing service before switching startup modes.
Run a task
Once coordinate calibration is complete and control enabled, have the Agent observe, start the task, observe its execution and stop.
| Tool signature | Behavior |
|---|---|
robot_get_observation(with_image=true) | Returns state and wrist image; false allows lightweight state polling |
robot_start_policy(instruction) | Starts a task and returns immediately; execution continues in the background |
robot_set_instruction(instruction) | Updates a running/paused instruction at the next inference without truncating the current action chunk |
robot_pause(with_image=true) | Stops sending new targets, holds position and returns an observation |
robot_resume() | Re-observes and resumes a paused run |
robot_stop(with_image=true) | Stops the policy or controlled motion and returns an observation |
Runs have no automatic time limit. A successful inference does not establish task completion. Keep observing with robot_get_observation and explicitly stop.
Updates, pause and resume must come from the entry point that owns the run. Stop a web-owned run before starting through the Agent. The browser retains Stop for Agent-owned runs.
Starting again with the same instruction after stopping continues the current local task's records and video but starts a new run. A different instruction creates a local task. robot_start_policy accepts only instruction, not the HTTP API's new_task parameter.
Model settings
| Tool signature | Behavior |
|---|---|
robot_get_policy_config() | Reads model address, ID, chunk wait and whether credentials are configured; never returns the key |
robot_configure_policy(url, model, inter_chunk_pause_s, api_key=None) | Saves complete model settings while idle; omit api_key to preserve credentials |
Example tool arguments:
robot_configure_policy(
url="https://api.pokebot.com/v1",
model="MODEL_ID",
inter_chunk_pause_s=0.5,
)Use the official Base URL, https://api.pokebot.com/v1, and a model ID returned by its /models endpoint. Saving checks /models; failure preserves the previous configuration. inter_chunk_pause_s is non-negative seconds and defaults to 0.5. Zero does not change the 30 Hz action rate. See Tasks and sessions for protocol requirements.
Calibration and devices
Follow the on-site procedure in coordinate calibration. Calibration tools default to with_image=false, except enabling control.
| Tool signature | Behavior |
|---|---|
robot_calibration_status(with_image=false) | Reads the phase, samples, control gate and local profile_file |
robot_calibration_begin(safety_confirmed, with_image=false) | Starts teaching and confirms the automatic return after C |
robot_calibration_accept_home(with_image=false) | Captures Home |
robot_calibration_set_guiding_axis(axis, with_image=false) | Selects Franka native translation axis x, y or z; release guiding buttons first |
robot_calibration_accept_plane_a(with_image=false) | Captures surface point A |
robot_calibration_accept_plane_b(with_image=false) | Captures B; A→B defines task +X |
robot_calibration_accept_plane_c(with_image=false) | Captures C and automatically returns Home; moves the arm |
robot_calibration_return_a(with_image=false) | Returns to A during B/C teaching; moves the arm |
robot_calibration_return_home(with_image=false) | Retries the Home return, retaining samples; moves the arm |
robot_calibration_finish(save_confirmed, with_image=false) | Saves calibration after a successful return; does not enable control |
robot_calibration_undo(with_image=false) | Removes the latest unsaved record without motion, retaining earlier records and saved calibration |
robot_calibration_enable_control(safety_confirmed, initialization_confirmed, with_image=true) | Enables control with saved calibration; may initialize and move the gripper |
robot_disconnect() | While idle, releases devices and discards unfinished teaching; retains saved calibration |
Capturing C, saving and enabling control are separate MCP steps. Confirmation parameters must come from the on-site operator's actual confirmation; the Agent's intent to complete a task is not a substitute. Undo cannot remove saved calibration; recalibrate to replace it.
Direction check
| Tool signature | Behavior |
|---|---|
robot_get_direction_check() | Returns at_home and active without moving |
robot_check_direction(direction, with_image=true) | Accepts forward, left, up or home; returns an observation after motion |
Control must be ready and idle. The first three trials start at Home, translate 5 cm along −Y/+X/+Z with Roll −30°/Pitch −30°/Yaw +30°, respectively, then return. home only returns. All preserve gripper opening and make no model request.
Stop cancels the rest of the trajectory, including the return. Explicitly return Home before another trial after stopping. See direction check to compare the motions.
Manual motion
| Tool signature | Behavior |
|---|---|
robot_move_to_pose(x=None, y=None, z=None, roll=None, pitch=None, yaw=None, gripper=None, relative=false, with_image=true) | Moves to a pose, retaining omitted components |
robot_move_waypoints(waypoints, with_image=true) | Executes a non-empty ordered list of waypoints |
robot_reset(with_image=true) | Opens the gripper and returns Home |
robot_recover(with_image=true) | Recovers hardware and returns Home |
These tools physically move the robot. Pose and waypoint motion require idle, calibrated and ready control.
| Pose parameter / waypoint field | Meaning |
|---|---|
x, y, z | Model-frame position in metres |
roll, pitch, yaw | Angles about model X/Y/Z axes in degrees |
gripper | Absolute opening in [0,1]; omitted keeps the opening |
relative | Defaults to false. True means offsets: from the current pose for a single move, or from the preceding target for waypoints; the first uses the current pose |
blend | Waypoints only, in metres; uses arm.blend_radius, default 0.02; 0 stops at the point, and the last point always stops |
Each waypoint inherits omitted components from the previous point. Unknown fields are rejected. with_image is a tool argument, not a waypoint field.
The motion range also applies to pose and waypoint targets. Out-of-range targets are clipped, and the next relative waypoint uses the clipped effective target. Ordinary motion starts inside the range; an explicit Home return may start outside. Paths do not perform obstacle detection.
Configure the range through the console or HTTP API. This version has no MCP tool to configure it.
Handle failures
Known runtime conditions return a structured object:
{"ok":false,"error":"loop_running","hint":"call stop() first","detail":"..."}Use local runtime errors to handle loop_running, calibration_required, control_not_ready and policy_unavailable. Other exceptions may arrive as MCP ToolError. Observe current state after a failure or timeout before repeating motion.