Skip to main content
Each PX4 + Gazebo simulation container starts a built-in MCP server alongside the autopilot and bridge. The IDE proxy connects to it automatically at simulation startup and registers its tools with the active AI agent session.

​
How It Works

When a simulation starts, the proxy:
  1. Discovers the container’s available tools via the MCP protocol
  2. Registers them with the agent under a namespaced prefix: sim0__ for the first container, sim1__ for the second, and so on
  3. Injects a mission workflow prompt as a system block into the agent session
The agent then sees the container tools alongside its 49 built-in tools. There is no user configuration required. Ports are allocated automatically — multiple containers can run simultaneously without conflicts.

​
Tool Reference

9 tools are exposed by the px4-gazebo-humble container image.
Arm the drone motors. The vehicle must be in ReadyToArm state. Call get_flight_state first to verify.No parameters.Returns: {"ok": true, "action": "arm"}Example prompt: “Arm the drone.”
Disarm the drone motors. Only safe when the vehicle is landed.No parameters.Returns: {"ok": true, "action": "disarm"}Example prompt: “Disarm after landing.”
Take off to a target altitude.
ParameterTypeDefaultDescription
altitude_mfloat5.0Target altitude in meters AGL (clamped to 1–120)
Returns: {"ok": true, "action": "takeoff", "altitude_m": 5.0}Example prompt: “Take off to 10 meters.”
Land at the current horizontal position.No parameters.Returns: {"ok": true, "action": "land"}Example prompt: “Land the drone.”
Navigate to a position relative to the home position. Offsets are in meters: x = North, y = East, z = altitude above ground (positive up).
ParameterTypeDefaultDescription
xfloat—North offset from home (meters)
yfloat—East offset from home (meters)
zfloat—Altitude AGL (meters, positive up)
yaw_degfloat0.0Heading in degrees (0 = North, 90 = East)
The vehicle must be airborne. The tool returns immediately after sending the setpoint — use wait_for_any with a sim_exec_background altitude-check script to detect arrival.Returns: {"ok": true, "action": "go_to", "x": 10, "y": 0, "z": 5, "yaw_deg": 0}
go_to takes North and East offsets in meters, plus altitude above ground (positive up). The built-in flight_goto tool uses ENU meters instead — choose whichever convention fits your mission.
Example prompt: “Fly 20 meters north at 10 meters altitude.”
Set the vehicle flight mode.
ParameterTypeDefaultDescription
modestring—HOLD, RTL, LAND, or TAKEOFF (case-insensitive)
For position setpoint control, use go_to instead.Returns: {"ok": true, "action": "set_flight_mode", "mode": "HOLD"}Example prompt: “Switch to hold mode.”
Return to the home position and land (RTL).No parameters.Returns: {"ok": true, "action": "return_to_launch"}Example prompt: “Return to home.”
Execute a Python script inside the container and return its output. Use for multi-step maneuvers that go beyond single tool calls.
ParameterTypeDefaultDescription
pathstring—Absolute path to the script inside the container
timeout_sfloat30.0Maximum execution time in seconds
Returns: {"ok": true, "exit_code": 0, "stdout": "...", "stderr": ""}Example prompt: “Run the waypoint mission script at /tmp/mission.py.”
Read-only snapshot of the current flight state: arm status, flight mode, altitude, position, and battery. No side effects. Use before arming to verify the vehicle is ready.No parameters.Returns:
{
  "armed": false,
  "flight_mode": "HOLD",
  "altitude_m": 0.0,
  "latitude_deg": 47.3977419,
  "longitude_deg": 8.5455938,
  "battery_pct": 100.0
}
Example prompt: “What is the drone’s current altitude and battery level?”

​
Mission Workflow Prompt

The prompt encodes correct PX4 mission sequencing — readiness checks, waypoint arrival detection, and error handling — so your own prompts require no additional instructions. The proxy fetches this prompt from the container at connection time and injects it as a system block into the agent session.

​
Coordinate Frames

The sim0__go_to tool uses North and East offsets in meters relative to home, with altitude above ground as a positive-up z value. The built-in flight_goto tool uses ENU meters. Both tools control the same vehicle — choose whichever coordinate convention is convenient for your mission. See Coordinate Frames for a full explanation of the NED/ENU distinction.