Connect an AI Assistant with the MCP Server

The MoveIt Pro MCP server exposes the running system to any Model Context Protocol client — Claude Desktop, Cursor, and similar AI assistants. Phase 0 is read-only: an assistant can inspect your Objectives, Behaviors, Waypoints, robot state, and logs to help you understand and debug a configuration. It cannot author, edit, or run anything.

What the assistant can see

Tools

The server advertises nine read-only tools:

Tool	Returns
list_objectives	Every Objective in the active robot configuration.
get_objective	One Objective's parsed Behavior Tree and metadata, by ID.
list_behaviors	The catalog of every registered Behavior, with ports.
get_behavior_details	One Behavior's metadata and ports, by ID.
list_waypoints	Every saved Waypoint, with joint state.
get_waypoint	One Waypoint, by name.
get_recent_logs	The tail of the most recently active ROS log file.
get_execution_status	The Objective Server's live state and running Objective.
get_robot_state	The robot's current joint positions and velocities.

The first seven read the active robot configuration off disk and work regardless of whether the robot is running. get_execution_status and get_robot_state query the live stack; they return a clear "runtime not available" error when the MoveIt Pro stack is not running.

Resources

The server also exposes browsable resources:

• moveit-pro://catalog/behaviors — the Behavior catalog as JSON.
• moveit-pro://config/current — the active robot configuration's name and directory listing.
• moveit-pro://robot/urdf — the robot URDF (read from the latched /robot_description topic; requires the stack to be running).
• moveit-pro://objective/{objective_id} — a resource template; read moveit-pro://objective/<id> for an Objective's parsed JSON, using an ID from the list_objectives tool.

Connect a client

The server is the moveit_pro_mcp_server console script, which speaks MCP over stdio. An MCP client spawns it as a subprocess and communicates over the process's standard input and output.

The script must run in an environment where the MoveIt Pro workspace overlay is sourced — that is, inside the MoveIt Pro container. Point your client at a command that execs into the running stack and starts the server.

Preview

In this release the client wraps a docker compose exec into the running stack. A first-class moveit_pro mcp launcher that starts the server as a standalone service — independent of the rest of the stack — is coming in a later release. Until then, the runtime tools (get_execution_status, get_robot_state) require the stack to be up.

Claude Desktop

Add the server to claude_desktop_config.json (Settings → Developer → Edit Config). Replace the compose file path and service name with your deployment's:

{
  "mcpServers": {
    "moveit-pro": {
      "command": "docker",
      "args": [
        "compose",
        "-f", "/path/to/your/moveit_pro/docker-compose.yaml",
        "exec", "-T", "agent_bridge",
        "bash", "-c",
        "source /etc/skel/.moveit-pro-bashrc && moveit_pro_mcp_server"
      ]
    }
  }
}

Restart Claude Desktop. The moveit-pro tools appear in the tool menu once the handshake succeeds.

Cursor

Add the same server to ~/.cursor/mcp.json (or a project-local .cursor/mcp.json):

{
  "mcpServers": {
    "moveit-pro": {
      "command": "docker",
      "args": [
        "compose",
        "-f", "/path/to/your/moveit_pro/docker-compose.yaml",
        "exec", "-T", "agent_bridge",
        "bash", "-c",
        "source /etc/skel/.moveit-pro-bashrc && moveit_pro_mcp_server"
      ]
    }
  }
}

Privacy considerations

The MCP server transmits whatever a tool or resource returns to the connected AI client (Claude Desktop, Cursor, etc.), which is an external service. In particular, get_recent_logs reads the ROS log directory and forwards log lines verbatim. Avoid writing sensitive values — tokens, passwords, private endpoint URLs — to RCLCPP_* log macros in custom Behaviors, since they would be visible to the AI client.

Troubleshooting

• No tools appear / handshake fails. Confirm the stack is running and that the compose file path and service name in the client config are correct. Run the args command by hand in a terminal — it should start and wait on stdin without printing errors.
• Runtime tools return "runtime not available". get_execution_status and get_robot_state need a running stack. Start MoveIt Pro, then retry.
• The URDF resource is empty. The URDF is published once at launch on the latched /robot_description topic. If the stack is not running, the resource is unavailable.