mavlink-mcp 是一个供应商中立的无人机能力层 + 模型上下文协议服务器，完全基于开放标准构建。它通过 MAVSDK (BSD-3-Clause) 将 AI 代理（Claude Desktop、Cursor、VS Code 以及任何其他 MCP 客户端）连接到支持 MAVLink 的无人机——PX4 SITL、ArduPilot SITL 和 Pixhawk 级自动驾驶仪。它不是封装协议消息，而是将 8 项飞行能力（遥测、飞行模式、解锁/上锁、起飞、降落、飞往指定点、任务、返航）暴露在同一个整洁的 API 后面，并默认启用安全护栏。
它是 rosbridge-mcp（AI 代理 ↔ ROS 2 机器人）的姊妹项目，并共享相同的理念：仅开放协议、默认只读的安全护栏、模拟优先、零遥测、MIT 许可证。
关于名称的说明： "mavlink-mcp" 是一个临时的工作名称。"MAVLink" 是 Dronecode 基金会的商标；项目名称可能会在公开发布前根据其商标政策的审查结果进行调整。
安全免责声明： 本项目是为模拟和研究而构建的。使用它驾驶真实飞行器完全由您自行承担风险和责任，包括遵守当地航空法律（注册、飞行许可、飞行员执照）。请参阅 SECURITY.md。
对于 AI 代理，能力胜过 400 个 SDK 函数。 代理询问 get_capabilities（"这架无人机能做什么？"），返回一组物理动作的小词汇表，并据此规划——模型端无需 MAVLink 知识。
天生供应商中立。 能力是用物理量（度、米、伏特）从开放规范中定义的——而不是从任何专有 SDK 表面复制。MAVSDK 适配器只是一种实现；未来的 ROS 2 适配器（重用 rosbridge-mcp）将实现相同的接口。
安全护栏是 API 的一部分，而非事后考虑。 只读模式是默认设置，解锁和起飞需要明确的操作员批准确认，每个命令的位置在到达自动驾驶仪之前都会检查高度上限和软地理围栏。
Related MCP server: ArduPilot MCP Server Sandbox
+--------------------+ stdio (MCP) +----------------------------------+ MAVLink (UDP) +------------------+
| AI client | <-----------> | mavlink-mcp | <-------------> | PX4 / ArduPilot |
| (Claude, Cursor, | | MCP server | via | SITL or real FC |
| VS Code, ...) | | └─ capability layer + policy | MAVSDK | (Pixhawk-class) |
+--------------------+ | └─ MAVSDK adapter | (BSD-3) +------------------+
+----------------------------------+
Python scripts use the same capability layer directly (mavlink_mcp.Drone).能力层 (Drone) 拥有所有策略——只读、确认、高度、地理围栏。适配器 (MavsdkAdapter) 仅将已批准的操作转换为 MAVLink；它是唯一导入 mavsdk 的模块。新的后端实现相同的 DroneAdapter 接口，并免费继承两个表面（MCP 工具 + Python 库）和每一个安全护栏。
pip install git+https://github.com/hieutachi/mavlink-mcp.git启动 PX4 SITL（参见 docs/simulator-quickstart.md — 一个 Docker 命令），然后添加到您的 MCP 客户端配置中：
{
"mcpServers": {
"mavlink": {
"command": "mavlink-mcp",
"env": { "MAVLINK_MCP_READONLY": "true" }
}
}
}然后询问您的代理："这架无人机能做什么，它现在在哪里？"
当您准备好飞行时（在模拟器中！），将 MAVLINK_MCP_READONLY 设置为 "false"。
12 个工具覆盖 8 项能力。所有工具返回 JSON；错误以 {"error": "...", "guardrail": true} 的形式返回，而不是抛出异常，以便代理可以读取并做出反应。
工具 | 能力 | 功能描述 | 是否变更？ |
| — | 车辆支持的功能 + 当前激活的安全护栏 | 否 |
| 遥测 | 位置、姿态、电池、GPS、模式、已解锁、空中状态 | 否 |
| 飞行模式 | 当前飞行模式（HOLD、MISSION、RTL ...） | 否 |
| — | 端点、连接状态、安全护栏配置 | 否 |
| 解锁/上锁 | 启动电机 | 是 — 需要 |
| 解锁/上锁 | 停止电机（在地面上） | 是 |
| 起飞 | 爬升到目标高度 | 是 — 需要 |
| 降落 | 在当前位置降落 | 是 |
| 飞行模式 | 暂停：停止并悬停在原地 | 是 |
| 返航 | 飞回起飞点并降落 | 是 |
| 飞往指定点 | 飞到一个航点并悬停 | 是 — 检查地理围栏 + 高度 |
| 任务 | 上传航点任务并启动 | 是 — 检查每个航点 |
您： 检查无人机，如果状态良好，在 20 米高度进行短距离巡逻。
代理： (调用
get_capabilities— 看到只读关闭，地理围栏 200 米；调用get_telemetry— GPSFIX_3D，10 颗卫星，电池 100%) 无人机状态良好。我需要您的批准才能解锁并起飞——确认吗？您： 确认，请继续。
代理： (调用
arm(confirm=true)、takeoff(altitude_m=20, confirm=true)，然后使用地理围栏内的 3 个航点调用fly_mission，监控get_telemetry，最后调用return_to_launch) 巡逻完成——无人机已返回起飞点并已上锁。
环境变量 | 默认值 | 描述 |
|
| MAVLink 端点（PX4 SITL 的板外端口）。使用 MAVSDK 2.x 时，旧语法 |
|
| 拒绝所有可能移动车辆的工具（参见安全） |
|
| 起飞/飞往指定点/任务的高度上限，相对于起飞点的米数。 |
|
| 围绕起飞点的软地理围栏半径，米。 |
让语言模型指挥飞行器是真实的风险，因此安全护栏比典型的 SDK 更严格：
默认只读。 与大多数工具不同，您必须通过 MAVLINK_MCP_READONLY=false 明确选择才能飞行。在只读模式下，所有遥测工具都可用；每个会修改状态的工具都会被拒绝，并附有清晰说明。
危险转换需要两步确认。 arm 和 takeoff 需要 confirm=true，工具描述指示代理首先获得人类批准——代理无法在单个自主步骤中合法起飞。
软地理围栏 + 高度上限。 每个命令的位置（飞往指定点和每个任务航点）在发送到自动驾驶仪之前，都会根据 MAVLINK_MCP_GEOFENCE_RADIUS_M（围绕起飞点）和 MAVLINK_MCP_MAX_ALTITUDE_M 进行验证。
安全操作保持无摩擦。 land、hold 和 return_to_launch 永远不需要确认——降级操作必须始终廉价。
这些检查是此进程内部的策略——不能替代自动驾驶仪自身的故障保护、在 PX4/ArduPilot 中配置的真实地理围栏、网络隔离或持遥控器的人类操作员。在考虑真实硬件之前，请阅读 SECURITY.md，并将真实世界的飞行视为需要根据当地航空法律（例如越南的无人机法令 288/2025 要求注册和飞行许可）进行注册/许可。
相同的能力层可以导入到脚本和笔记本中——参见 examples/patrol_sitl.py 以获取针对 SITL 的完整起飞→航点→降落运行示例：
from mavlink_mcp import Drone, GuardrailConfig
from mavlink_mcp.adapters.mavsdk_adapter import MavsdkAdapter
drone = Drone(MavsdkAdapter(), guardrails=GuardrailConfig(readonly=False))
snapshot = await drone.get_telemetry()
await drone.arm(confirm=True)
await drone.takeoff(20.0, confirm=True)无遥测，无数据收集。 此包打开的唯一网络连接是您配置的 MAVLink 端点（MAVLINK_MCP_URL）。工具返回的车辆数据仅发送到您的 MCP 客户端。
许可证合规性。 核心故意依赖 MAVSDK-Python (BSD-3-Clause)，而不依赖 pymavlink (LGPL-3)，从而在此项目的 MIT 许可证下保持依赖树的宽松性。直接依赖项：mavsdk (BSD-3-Clause)、fastmcp (Apache-2.0)。此仓库中的所有代码都是根据公开的开放规范（MAVLink 协议文档、MAVSDK 文档）编写的原创作品——没有专有 SDK、没有逆向工程、没有接受供应商 EULA。
我需要无人机吗？ 不需要。MVP1 是模拟优先的：一切都可以在 PX4 SITL（一个 Docker 命令）上运行，并且设计为也能在 ArduPilot SITL 上运行。请参阅 docs/simulator-quickstart.md。
它能与 ArduPilot 一起工作吗？ 能力层通过 MAVSDK 同时支持 PX4 和 ArduPilot。PX4 SITL 是 MVP1 中主要测试的目标；ArduPilot SITL 的兼容性说明在快速入门中，在 CI 中验证它是路线图上的一个项目。
为什么不直接使用 MAVSDK？ 如果您手动编写 Python，请直接使用！mavlink-mcp 添加了 MAVSDK 没有的层：面向 AI 代理的 MCP 工具表面、具有运行时发现的能力模型，以及在协议之上强制实施的生产级安全护栏（只读、确认、地理围栏）。
代理说没有发现车辆。
检查 SITL 是否正在运行，并且是否向 MAVLINK_MCP_URL 中的端点发送 MAVLink（PX4 SITL 默认发送到 UDP 14540）。快速入门中有一个故障排除表。
我的数据会被发送到任何地方吗？ 仅发送到您的 MCP 客户端，它会将其转发给您使用的任何 LLM——请相应地处理位置数据。
阶段性计划见 ROADMAP.md：MVP1（当前——能力层 + MCP 服务器在 SITL 上）、MVP2（真实 Pixhawk 级硬件、重用 rosbridge-mcp 的 ROS 2 适配器、插件/一致性系统）、MVP3（社区适配器、多机、开放核心服务）。
欢迎贡献——请参阅 CONTRIBUTING.md。请签署您的提交（DCO）。注意清洁贡献规则：PR 必须仅基于公共规范和文档。
MIT——参见 LICENSE。依赖项许可证是宽松且兼容的：mavsdk (BSD-3-Clause)、fastmcp (Apache-2.0)。核心中没有 GPL/LGPL/AGPL 依赖项。
mavlink-mcp là lớp capability trung lập (vendor-neutral) cho UAV kèm MCP server, xây hoàn toàn trên chuẩn mở: kết nối AI agent (Claude Desktop, Cursor, VS Code...) với drone nói MAVLink (PX4/ArduPilot) qua thư viện MAVSDK (BSD-3). Đây là dự án chị em của rosbridge-mcp.
8 项能力： 遥测（位置/姿态/电量/GPS）、飞行模式、解锁/锁定、起飞、降落、前往、任务、返航 — 12 个 MCP 工具。
默认安全： 只读模式默认开启（MAVLINK_MCP_READONLY 默认 true）；解锁和起飞需在操作员同意后设置 confirm=true；可配置软禁飞区和高度上限。
仿真优先： 使用 PX4 SITL 运行（1 条 Docker 命令） — 参见 docs/simulator-quickstart.md。该项目适用于仿真/研究；实际飞行完全由您自行负责，包括根据《人民防空法 49/2024》和《288/2025 法令》进行设备注册和飞行许可申请。
名称“mavlink-mcp”为暂定名称 — 将在发布前根据 Dronecode 的商标政策进行审查。
Arm the vehicle (spin up motors). DANGEROUS on real hardware.
Rejected in readonly mode. Additionally requires confirm=true: ask the human operator for approval first — never set confirm=true on your own initiative. Preflight: check get_telemetry (GPS fix, battery) before arming. Returns {"armed": true} or {"error": ...}.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully compensates for the lack of annotations by disclosing that the tool is 'DANGEROUS on real hardware', that it is 'Rejected in readonly mode', and that it returns specific outputs ('{"armed": true}' or error). It also details required confirmation workflow and preflight checks, providing comprehensive behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured: a bold headline, a warning on the first line, critical usage rules for parameters and readonly behavior, a preflight instruction, and return format—all in just three sentences. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of this dangerous operation, the description covers all critical aspects: action, danger level, parameter semantics, error handling, preconditions, and output format. The output schema exists and matches the return values mentioned. No gaps remain for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema has 0% description coverage, the description adds essential meaning to the 'confirm' parameter by explaining its role in requiring human approval and explicitly instructing the agent never to set it to true autonomously. This goes well beyond the schema's bare type and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Arm the vehicle (spin up motors)' with a specific verb-resource pair ('arm' + 'vehicle'). It also distinguishes from sibling tools like 'disarm' and 'takeoff' by explicitly marking this as the arming action and noting its preflight dependencies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it requires human approval via confirm=true, and specifies that the agent must never set confirm=true on its own initiative. It also tells when to use this tool (after checking get_telemetry for GPS fix and battery) and indicates it is rejected in readonly mode, offering clear context for when not to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Disarm the vehicle (stop motors). Autopilots reject this in flight.
Rejected in readonly mode. Returns {"disarmed": true} or {"error": ...}.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the core behavior (stop motors), rejection conditions, and return format. It does not detail side effects or reversibility, but for a disarm command this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences), front-loads the main purpose, and adds constraints and return format without redundancy. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, an output schema (implied by return description), and clear behavior, the description is complete for an agent to select and invoke the tool correctly. It covers purpose, constraints, and expected output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters (100% coverage), so the description is not required to add parameter details. It adds value by describing the return value format, which is helpful for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Disarm the vehicle (stop motors)') and distinguishes it from siblings like 'arm' and 'takeoff'. It also specifies conditions where it is rejected, enhancing clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when the tool is rejected ('in flight', 'in readonly mode'), which guides appropriate usage. However, it does not explicitly mention alternatives or when-not-to-use in a comparative sense, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a waypoint mission and start flying it. The vehicle must be armed and flying (or the autopilot will take off per its mission config).
Args: waypoints: List of {"latitude_deg", "longitude_deg", "relative_altitude_m", "speed_m_s"?} objects, flown in order. Every waypoint is validated against the altitude ceiling and the soft geofence before anything is uploaded.
Rejected in readonly mode. Returns {"mission_started": true, "waypoint_count": N}. Use hold to pause or return_to_launch to abort; poll get_flight_mode — mode leaves MISSION when the mission ends.
| Name | Required | Description | Default |
|---|---|---|---|
| waypoints | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses: rejection in readonly mode, return value format, per-waypoint validation against altitude ceiling and soft geofence, precondition with fallback behavior (autopilot takeoff), and mode lifecycle ('mode leaves MISSION when the mission ends'). This is comprehensive and reveals all key behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose, then preconditions, parameter details, limitations, return value, and sibling usage. Every sentence adds value; there is no fluff. It could be slightly tighter (e.g., combining precondition and fallback), but the structure is logical and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (one parameter, clear input/output) and the presence of an output schema (though not shown), the description covers input structure, preconditions, validation, return value, and post-action guidance. It lacks explicit error cases beyond readonly mode rejection, but overall it provides enough information for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (the schema only shows an array of objects with 'additionalProperties: number'). The description compensates fully by specifying the exact object fields: latitude_deg, longitude_deg, relative_altitude_m, and optional speed_m_s. It also explains validation behavior, adding meaning that the agent cannot infer from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Upload a waypoint mission and start flying it', which is a specific verb+resource. It clearly distinguishes from sibling tools like takeoff (just take off), hold (pause), and return_to_launch (abort) by explicitly mentioning them as alternatives. The scope (waypoint mission vs other actions) is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states prerequisites: 'The vehicle must be armed and flying (or the autopilot will take off per its mission config)' and notes rejection in readonly mode. It also directs to use hold or return_to_launch for pausing or aborting. While it doesn't explicitly say 'use this when you have a waypoint list vs. use takeoff for simple ascent', the context and sibling differentiation provide sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover what this vehicle can do and which guardrails are active.
Takes no arguments; does not require a live vehicle. Call this first. Returns {"adapter", "capabilities": ["telemetry", "arm_disarm", ...], "guardrails": {"readonly", "max_altitude_m", "geofence_radius_m"}, "connected"}. Plan only with listed capabilities; if "readonly" is true, every tool that can move the vehicle will be rejected.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It transparently discloses that the tool takes no arguments, does not require a live vehicle, and returns a specific structure with fields like 'capabilities' and 'guardrails'. It also explains the behavioral impact of the 'readonly' guardrail on other tools.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured. It front-loads the purpose, then provides key details (no arguments, no live vehicle needed, call first), and ends with the return shape and an important behavioral note. Every sentence earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has zero parameters and an output schema exists, the description does an excellent job of explaining the output structure and its implications. It covers the return fields, the meaning of 'readonly', and the recommended usage order, making it fully complete for a discovery tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty with 0 parameters, so there is no need to explain parameters. The description adds value by explicitly stating 'Takes no arguments' and 'does not require a live vehicle', which clarifies usage beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: 'Discover what this vehicle can do and which guardrails are active.' It uses a specific verb and resource, and distinguishes itself from sibling tools (e.g., get_flight_mode, arm) by being the only one that returns capabilities and guardrails and is safe to call without a live vehicle.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call this first' and instructs to 'Plan only with listed capabilities; if "readonly" is true, every tool that can move the vehicle will be rejected.' This provides clear guidance on when to use this tool and its implications for subsequent tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report the MAVLink endpoint, connection state, and guardrail config.
Takes no arguments. The connection is opened lazily, so "connected" is false until another tool has been used. Check this first when other tools report errors.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the critical lazy-connection behavior ('connected is false until another tool has been used') which is essential for correct interpretation of the result. This exceeds expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences front-loading purpose, then providing essential behavioral context and usage guidance. Every sentence is necessary and earns its place. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has zero parameters and an output schema. Given this simplicity, the description is fully complete: it explains what is reported, the lazy-connection nuance, and the diagnostic usage pattern. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with zero parameters, so baseline is 3. The description adds value by stating 'Takes no arguments' upfront, confirming no hidden inputs. A 4 is appropriate for a param-free tool where the description reinforces the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports the MAVLink endpoint, connection state, and guardrail config. It is a singular, specific verb+resource combination that is easily distinguished from sibling tools like arm, takeoff, or get_telemetry.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent to check this first when other tools report errors, and explains the lazy-connection behavior that makes this diagnostic. It provides clear context for when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report the current flight mode (e.g. HOLD, TAKEOFF, MISSION, RTL).
Takes no arguments. Read-only. Returns {"flight_mode": "HOLD"}.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clearly states 'Read-only' and provides an example return value. This discloses the core behavioral trait. However, it does not mention error handling, connection prerequisites, or rate limits, which are minor gaps for a simple read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose, and contains no extraneous information. Every sentence serves a clear function: stating the purpose, noting no arguments, and giving an example output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, simple output), the description is nearly complete. It covers what the tool does, its input, and its output format. It does not explain possible errors or connection requirements, but for a straightforward getter, this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100%. The description adds 'Takes no arguments,' which is redundant but confirms the schema. For a zero-parameter tool, baseline is 4, and the description does not detract from it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Report the current flight mode (e.g. HOLD, TAKEOFF, MISSION, RTL).' The verb 'report' and resource 'flight mode' are specific, and the examples distinguish it from the sibling action commands (e.g., arm, takeoff, land).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies read-only usage by stating 'Takes no arguments. Read-only,' but it does not explicitly say when to use this tool versus alternatives. No guidance on when not to use it or in what contexts (e.g., before taking action). However, the sibling set includes many write commands, so the intent is somewhat clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one snapshot of the vehicle's telemetry. Read-only.
Takes no arguments. Returns {"position": {latitude_deg, longitude_deg, absolute_altitude_m, relative_altitude_m}, "attitude": {roll_deg, pitch_deg, yaw_deg}, "battery": {voltage_v, remaining_percent}, "gps": {num_satellites, fix_type}, "flight_mode", "armed", "in_air"}. Fields the vehicle did not report within a few seconds are null. Always check telemetry before commanding motion.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It discloses 'Read-only' behavior and that fields not reported within a few seconds are null. It does not cover connectivity scenarios or refresh semantics, but the null-handling is a valuable behavioral trait.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no wasted words. It front-loads the purpose and key traits, then efficiently provides return structure, null handling, and a usage advisory.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an existing output schema, the description is complete. It covers the tool's purpose, behavior (null fields), and use-case advisory. No obvious gaps remain for a simple telemetry read.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters and schema coverage is 100%. The description adds value beyond the schema by explicitly listing the returned fields (position, attitude, battery, gps, flight_mode, armed, in_air) with their subfields, which aids an agent in understanding what to expect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read one snapshot of the vehicle's telemetry. Read-only.' It uses a specific verb ('Read') and resource ('telemetry snapshot'), and the purpose is distinct from siblings like `get_flight_mode` or `get_capabilities`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly advises when to use the tool with 'Always check telemetry before commanding motion,' and declares it read-only (safe, no side effects). It does not explicitly state when not to use it or list alternatives, but the sibling context provides differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fly to a single waypoint and loiter there. The vehicle must be flying already (armed + taken off).
Args: latitude_deg: Target latitude (WGS84). longitude_deg: Target longitude (WGS84). relative_altitude_m: Target altitude above the launch point, in meters. Checked against the altitude ceiling. yaw_deg: Heading at the target, 0 = north (default 0).
Rejected in readonly mode. The target is also checked against the soft geofence around home (MAVLINK_MCP_GEOFENCE_RADIUS_M, default 200 m). Returns {"goto_started": true, "target": {...}} — travel is asynchronous; poll get_telemetry to track progress.
| Name | Required | Description | Default |
|---|---|---|---|
| yaw_deg | No | ||
| latitude_deg | Yes | ||
| longitude_deg | Yes | ||
| relative_altitude_m | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations were provided, so the description carries the full burden of behavioral disclosure. It clearly states the tool is destructive (it sends a movement command) by noting it is 'Rejected in readonly mode.' It also describes the asynchronous nature of the travel ('travel is asynchronous; poll get_telemetry to track progress'), which is critical behavioral context. It could have mentioned if the command is reversible (e.g., can it be cancelled mid-flight?), but the description is strong for a tool with zero annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph with an Args section and behavioral notes. It is front-loaded with the core action and precondition. Every sentence adds useful information. It is somewhat long at ~100 words, but this length is justified given the four parameters and the need to explain behavior. Minor inefficiency: the Args section could be more concise by relying on the schema, but since schema coverage is 0%, the verbosity is warranted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters with 0% schema coverage, no annotations, and an output schema exists. The description provides a complete understanding: it explains each parameter, notes the prerequisite (must be flying), mentions safety checks (geofence, altitude ceiling), and describes the return value format (including an example). However, it does not explicitly document all output schema fields (just a partial example), and it misses any mention of error conditions or failure scenarios (e.g., what happens if the geofence limit is exceeded). For a tool with this complexity, the description is nearly complete but has a small gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the input schema provides no descriptions for the parameters. The description compensates by listing and explaining each parameter inline in the docstring. For example, it states 'yaw_deg: Heading at the target, 0 = north (default 0).' It also provides constraints: 'relative_altitude_m: Checked against the altitude ceiling.' This adds value beyond the raw schema, but the documentation is embedded in the text rather than structured. Baseline is 3 due to zero coverage, and the description meets that baseline adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Fly to a single waypoint and loiter there.' The verb 'fly' and resource 'single waypoint' are specific, and the description distinguishes this tool from siblings like 'fly_mission' (which handles multiple waypoints) and 'return_to_launch' (which returns home). The title is missing, but the description compensates fully.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states a prerequisite: 'The vehicle must be flying already (armed + taken off).' This tells the agent when it is appropriate to use this tool (only after arming and takeoff). It also mentions constraints like the altitude ceiling and soft geofence, guiding proper invocation. No explicit when-not-to-use is given, but the negative condition ('not armed/taken off') is strongly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pause: stop and loiter at the current position (HOLD mode).
Rejected in readonly mode. Use this to interrupt a goto or mission safely. Returns {"holding": true}.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the rejection in readonly mode and the return value. However, it does not elaborate on side effects like whether the mission is paused or aborted, which would be useful for a safety-critical tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences, front-loaded with the key purpose. Every sentence earns its place with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 params, no nested objects, output schema exists), the description covers purpose, usage, behavior, and return value. It is fully adequate for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so baseline is 4. The description does not need to add parameter info since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Pause: stop and loiter') and the resource ('current position', 'HOLD mode'). It distinguishes this from sibling tools like goto_location and fly_mission by focusing on interruption.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use ('interrupt a goto or mission safely') and when not ('Rejected in readonly mode'). This provides clear guidance on context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Land at the current position.
Rejected in readonly mode (no confirmation needed — landing makes the vehicle safer). Returns {"landing_started": true}; poll get_telemetry until "in_air" is false.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description adequately discloses behavioral traits: it is rejected in readonly mode, landing enhances safety, and it returns a specific JSON object. It also recommends polling for completion, which adds useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, each earning its place. The first sentence defines the action succinctly, and the second adds essential behavioral details and post-call advice without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema (though context signals oddly indicate one), the description fully covers purpose, rejection condition, return value, and next steps. No gaps remain for an agent to invoke and understand the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the schema provides no additional information. The description adds value by specifying the return format and polling guidance, which is more than the baseline for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Land at the current position', using a specific verb and resource scope. It distinguishes itself from sibling tools like 'takeoff' and 'hold', making the action unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the tool is rejected in readonly mode and that no confirmation is needed, providing clear context for when it can be used. It also advises polling get_telemetry after use, but does not explicitly compare to other landing-related actions like 'return_to_launch'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fly back to the launch point and land there (RTL).
Rejected in readonly mode (no confirmation needed — RTL is a recovery action). Returns {"rtl_started": true}; poll get_telemetry until "in_air" is false.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses key behavior: rejection in readonly mode, no confirmation need, the exact return value, and instructions to poll get_telemetry until 'in_air' is false. This is thorough behavioral guidance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding value: action, exception/confirmation, return/polling. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter command, the description is complete: it explains the action, the readonly restriction, the return shape, and the follow-up monitoring step. An agent can invoke and verify the operation successfully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds no unnecessary parameter information, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action: 'Fly back to the launch point and land there (RTL).' This is a specific verb+resource and clearly distinguishes it from sibling tools like land or goto_location.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context: RTL is a recovery action, rejected in readonly mode, and requires no confirmation. While it does not explicitly compare to alternatives, the recovery role and the exclusion are enough to guide usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Take off vertically to altitude_m meters above the launch point.
Rejected in readonly mode. Additionally requires confirm=true after human operator approval — never set it on your own initiative. The vehicle must be armed first (call arm). Altitude is validated against the configured ceiling (MAVLINK_MCP_MAX_ALTITUDE_M, default 50 m).
Returns {"takeoff_started": true, "target_altitude_m": ...} — takeoff is asynchronous; poll get_telemetry to watch the climb.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | ||
| altitude_m | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral traits such as altitude validation against a configured ceiling with a default value, and the asynchronous nature of the operation. Since no annotations are provided, the description carries the full burden, and it handles this well, though it could also mention safety implications or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise, providing essential information in three focused paragraphs: purpose, usage constraints, and return value. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema, the description provides adequate context about the return value and asynchronous behavior. It covers prerequisites, restrictions, and cited alternatives, making it complete for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the parameters, explaining that 'altitude_m' is meters above launch point and validated against a ceiling, and that 'confirm' requires human approval. With 0% schema description coverage, the description fully compensates, though it does not list the exact default values from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool makes the vehicle 'take off vertically to `altitude_m` meters above the launch point', providing a specific verb and resource. It distinguishes itself from sibling tools like 'land' or 'arm' by describing a distinct flight action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when the tool is rejected ('Rejected in readonly mode'), requires specific user confirmation ('confirm=true after human operator approval'), and lists prerequisites ('The vehicle must be armed first (call arm)'). It provides clear usage guidance without ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0armdisarmfly_missionget_capabilitiesget_connection_statusget_flight_modeget_telemetrygoto_locationholdlandreturn_to_launchtakeoffScored across 12 tools
Each tool has a clearly distinct purpose: read operations (get_flight_mode, get_capabilities, get_telemetry, get_connection_status), safety actions (arm, disarm), and navigation commands (takeoff, land, hold, return_to_launch, goto_location, fly_mission). No overlap or ambiguity.
Most tools use a consistent verb_noun pattern with snake_case (e.g., get_flight_mode, get_telemetry). Action verbs are single words (arm, disarm, takeoff, land, hold) except return_to_launch and goto_location, which are phrases. The pattern is clear and predictable, with only minor deviation.
12 tools is well-scoped for a drone control server. It covers essential read capabilities, safety, and navigation without being excessive. Each tool has a clear role and contributes to a complete workflow.
The toolset covers core drone operations: reading state, arming, disarming, takeoff, landing, holding, returning, going to a location, and flying missions. Minor gaps exist, such as no direct parameter setting or mode change tool, but the core workflows are fully supported and the guardrails are well-integrated.
Connect Claude, Cursor, Codex, and other AI tools to your robotics mission data.
Connect, monitor, and control AI agents — tasks, approvals, schedules, and governance.
Build, validate, and deploy multi-agent AI solutions from any AI environment.
Your AI Agent's Infrastructure Layer. Connect Claude, Copilot, Codex, or ChatGPT to 200+ managed open source services. Start databases, pipelines, and applications through natural language.
