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

MoveIt Pro provides two transports backed by the same tools and resources:

• Authenticated Streamable HTTP at https://<host>:<rest-port>/mcp. The default deployment uses REST port 3200; named instances use their assigned REST port.
• The moveit_pro_mcp_server stdio console script for clients running on the same machine.

Streamable HTTP is the preferred transport for a remote client. It uses the deployment's existing TLS certificate and requires Authorization: Bearer <MOVEIT_FRONTEND_KEY> on every MCP request; browser CORS preflight requests remain unauthenticated. Install or trust the MoveIt Pro Runtime certificate as described in Endpoint Security.

The HTTP endpoint permits loopback Host and Origin values by default. Before connecting through a hostname or network address, add its exact Host header to MOVEIT_MCP_ALLOWED_HOSTS. Browser-based MCP clients must also list their page origins in MOVEIT_MCP_ALLOWED_ORIGINS. Native clients normally omit the Origin header.

Host allowlist applies to direct connections only

The Host allowlist protects direct connections to the REST port. Requests routed through the web frontend's proxy as /api/mcp arrive at the Runtime backend with a rewritten loopback Host header, so MOVEIT_MCP_ALLOWED_HOSTS does not constrain them — for proxied traffic, the bearer key and the Origin allowlist are the effective controls.

export MOVEIT_MCP_ALLOWED_HOSTS="robot.example.com:3200"
export MOVEIT_MCP_ALLOWED_ORIGINS="https://agent.example.com"
moveit_pro run

For stdio, the client spawns the console script and communicates over standard input and output. The script must run inside the MoveIt Pro container, where the workspace overlay is sourced.

Protocol compatibility

The server supports the sessionless MCP 2026-07-28 protocol and the earlier session-based 2025-11-25 protocol over stdio. Streamable HTTP uses the stateless 2026-07-28 transport. The tools and resources have the same application-level semantics over either transport.

Streamable HTTP

Configure a current MCP client with:

• URL: https://<host>:<rest-port>/mcp
• Header: Authorization: Bearer <MOVEIT_FRONTEND_KEY>
• A trusted CA or Runtime certificate for TLS verification

The MCP endpoint shares the REST port. To find a deployment's REST port remotely, query the instance discovery server on port 3204.

stdio

stdio clients spawn moveit_pro_mcp_server inside the MoveIt Pro container and speak MCP over the process's standard streams. It supports both the 2026-07-28 and legacy 2025-11-25 protocol eras.

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", "runtime",
        "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 connection 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", "runtime",
        "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

• HTTP returns 401 Unauthorized. Configure the client to send the deployment's MOVEIT_FRONTEND_KEY as a bearer token.
• HTTP returns 421 Misdirected Request. Add the endpoint's exact Host header, including its port, to MOVEIT_MCP_ALLOWED_HOSTS.
• HTTP returns 403 Invalid Origin header. Add the browser client's exact origin to MOVEIT_MCP_ALLOWED_ORIGINS. Native clients should omit Origin.
• HTTP returns 408 Request Timeout. The full request body must arrive within 30 seconds; check for a slow or unreliable network link between the client and the deployment.
• HTTP returns 413 Request Entity Too Large. Keep each MCP request body at most 1 MiB.
• HTTP returns 429 Too Many Requests. Retry after the response's Retry-After interval; one Runtime worker admits up to 16 concurrent MCP requests.
• HTTP returns 504 Gateway Timeout. The server bounds how long a single MCP request may spend processing after upload. A healthy deployment answers well inside that bound; a 504 usually points at unresponsive storage backing the robot configuration or log directories.
• TLS verification fails. Install the Runtime certificate or configure the client with its CA. Do not disable verification for a remote deployment.
• No stdio tools appear. Confirm the stack is running and that the compose file path and service name in the client configuration are correct. Run the args command by hand in a terminal; it should start and wait on stdin without printing errors.
• get_execution_status / get_robot_state return "runtime not available". These two tools 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.