mcp-drone-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-drone-mcp submit the 12-variant experiment to idle drones and watch status"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-drone-os
An Arch-based, LAN-only disposable agent runner. The project builds a bootable USB image with hardened SSH, per-agent Unix identities, isolated SMB shares, an MCP bridge, and a local control-plane dashboard.
Architecture
Run one coordinator on the laptop where the host agent lives. Booted machines are drones. The host agent connects to one local MCP server; the coordinator keeps fleet state and later maintains one persistent SSH control connection per drone. Drones run one-shot jobs or durable services.
host agent -> local mcp-drone-mcp -> coordinator state -> SSH -> dronesJob submission is batched. A twelve-variant experiment is one MCP call, not twelve independent shell conversations. A drone advertises available slots and capabilities; placement can be explicit or capability-aware.
Related MCP server: 2native-ssh-mcp
Features
This repository contains the contracts and safe host-side tooling needed for the first image profile:
mcp-drone-os validatevalidates an agent manifest without network access.mcp-drone-os deviceslists removable block devices.mcp-drone-os writerequires--yes, an exact device confirmation, and a removable-disk check before writing.mcp-drone-os eventsappends and reads the legacy JSONL event format.mcp-drone-mcpprovides a local JSON-RPC stdio MCP gateway.mcp-drone-agentprovides a persistent JSON-lines worker protocol for launching, inspecting, and reading logs from transient systemd tasks.mcp_drone_os.ssh_transport.SSHDronekeeps one SSH worker stream alive and uses OpenSSH connection multiplexing for repeated operations.The coordinator stores drones, tasks, artifacts, and audit events in SQLite.
The MCP gateway exposes registration, batch submission, status, bounded logs, artifact listing/fetching, cancellation, reconciliation, persistence promotion, and user-event recording.
run_jobsaccepts many variants in one call. Each job can select a drone; otherwise placement uses available slots. Jobs support one-shot work, durable services, and long-lived provisioning work.Each drone uses a persistent JSON-lines SSH worker stream plus OpenSSH connection multiplexing. The host agent sends coarse batch operations rather than starting a new SSH process for every command.
Drones use per-agent Unix accounts, transient systemd units with CPU, memory, and process limits, and rootless Podman/Quadlet for durable services.
Enrollment supports agent keys, a separate controller key, and an OpenSSH host certificate signed by a coordinator-held CA. Password and root SSH are disabled.
A preconfigured image boots without a framebuffer login: it creates declared agent accounts, installs the controller key, derives a unique
mcp-drone-<NIC>hostname, records IP/CPU/memory in/run/mcp-drone/identity, and advertises_ssh._tcpover mDNS.runner/profile/is an ArchISO profile with the minimal runtime package set, SSH hardening, first-boot enrollment hook, and systemd target.tools/test-image.shboots a built image in QEMU with SSH forwarded to port 6022.
Install and use
python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[test]'
mcp-drone-os validate examples/manifest.json
mcp-drone-os devices
# Start the local MCP gateway for an MCP client
mcp-drone-mcp
# The coordinator can also be inspected directly
mcp-drone-os fleet --state /var/lib/mcp-drone/coordinator.dbLaunch mcp-drone-mcp as a local stdio MCP server for the host agent. The
dashboard is optional and defaults to localhost; view it remotely through SSH
port forwarding. Use TLS and a network boundary before exposing it on a LAN.
USB-only operation
After the ISO is built, the runtime does not need this repository, Python packages, or an internet connection. Boot the USB and use the bundled commands:
/usr/local/bin/mcp-drone-os fleet --state /var/lib/mcp-drone/coordinator.db
/usr/local/libexec/mcp-drone-mcpAn MCP client on another computer can use the USB-hosted coordinator over SSH
by launching /usr/local/libexec/mcp-drone-mcp as its SSH stdio command. The
dashboard is available through ssh -L 8787:127.0.0.1:8787 ...; it is not
exposed on the LAN by default. Enrollment and remote multi-drone jobs still
need LAN connectivity to the other machines, but the USB itself is the
complete control-plane/runtime artifact.
Build an image after installing Arch’s archiso package:
tools/build-image.sh out
tools/test-image.sh out/mcp-drone-os-0.1.0-x86_64.isoFor a dedicated machine, boot the ISO and run the guarded persistent installer from the live shell. It repartitions the selected whole disk, creates a LUKS2-encrypted root, installs the runner filesystem, and configures BIOS and UEFI GRUB boot paths:
/usr/local/bin/mcp-drone-install \
--device /dev/sda --confirm-device /dev/sda --yesThe installer asks for the device path a second time and prompts for the disk passphrase. Verify the target carefully: this operation destroys all existing partitions on that disk. The live image remains the recommended disposable mode when a machine should be reset by rebooting.
The image configures wired Ethernet and USB Ethernet for DHCP through systemd-networkd. Wi-Fi credentials are intentionally not baked into the generic image; configure the appropriate network profile on machines that need wireless operation.
To bake a runner enrollment bundle into the image, set both
MCP_DRONE_MANIFEST and MCP_DRONE_ENROLLMENT. The enrollment JSON must
reference /etc/mcp-drone/manifest.json; the builder copies the selected
manifest to that path. Enrollment tokens are secrets and should not be
committed to the repository.
To make a USB immediately accept work from one controller, also provide its public key at build time. It is copied into the image but is not committed:
MCP_DRONE_MANIFEST=manifest.json \
MCP_DRONE_ENROLLMENT=enrollment.json \
MCP_DRONE_CONTROLLER_PUBLIC_KEY="$HOME/.ssh/id_ed25519.pub" \
tools/build-image.sh out-readyThe enrollment manifest declares the agent IDs that become
drone-<id> Unix accounts. Discover a runner with
avahi-browse -rt _ssh._tcp, then register its advertised hostname and SSH
account with the coordinator. register_drone accepts ssh_user for hosts
whose SSH username differs from the default mcp-control.
For an offline/preconfigured runner, start with
examples/enrollment.json; add coordinator_url and a one-time token when
the coordinator is available on the LAN.
Enrollment URLs must use HTTPS by default. For a temporary isolated lab only,
allow_insecure: true can be set in the enrollment bundle. The dashboard
supports --tls-cert and --tls-key when it must be reachable from a LAN;
otherwise keep its localhost default and use SSH forwarding.
For authenticated host enrollment, configure the coordinator with
MCP_DRONE_ENROLL_TOKEN and MCP_DRONE_SSH_CA_KEY. The drone generates its
own host key on first boot and receives an OpenSSH host certificate; the CA
private key never goes into the image.
SMB is intentionally optional. Install samba in a custom profile, generate
/etc/samba/mcp-drone-shares.conf with mcp_drone_os.shares.render_shares,
then enable mcp-drone-smb.service. Agent homes remain accessible over SFTP
without enabling Samba.
Parallel example: 12 experiments on 3 machines
Register three runners with four slots each. Submit one batch through MCP:
{
"agent_id": "research-agent",
"mode": "once",
"defaults": {"limits": {"cpu_quota": "200%", "memory_max": "2G", "tasks_max": 256}},
"jobs": [
{"command": ["./run-test", "--variant", "0"]},
{"command": ["./run-test", "--variant", "1"]},
{"command": ["./run-test", "--variant", "2"]}
]
}Continue the array through variant 11. The coordinator persists all tasks,
dispatches up to the available slots, and fills slots as work finishes. Use
fleet_snapshot or reconcile_running for progress, then task_artifacts
and fetch_artifact to collect results. The laptop handles coordination and
metadata; the three drones perform the CPU and I/O work.
For scripts or repositories, call stage_bundle once per destination drone,
then have the batch commands reference
/var/lib/mcp-drone/staging/<bundle-id>. Jobs submitted for agent_id=alpha
run as the provisioned drone-alpha Unix account, so the manifest must declare
that agent on each target runner.
Current boundaries
This is a small v1 runner, not a general cluster scheduler. It does not flash media automatically, provide browser login, or implement remote HTTP MCP. Persistence promotion still expects an already-mounted data volume; the separate persistent installer handles whole-disk installation and LUKS2 root encryption. SMB, Kubernetes, and remote MCP transport remain optional future work.
USB writes are destructive and are never part of the build step. The image enrollment hook is intentionally explicit: it only registers when given a coordinator URL and one-time token.
Security defaults
The image profile disables root/password SSH, accepts only declared public keys, binds services to the private interface, and creates one Unix identity and share root per agent. The host builder never guesses a target disk.
Repository layout
schemas/manifest.schema.json manifest contract
src/mcp_drone_os/ coordinator, MCP gateway, and state
runner/profile/ bootable ArchISO profile
runner/systemd/ service templates
tools/ image build and QEMU test entrypoints
tests/ unit and contract testsAvailable Tools
13 toolscancel_taskB
Cancel a queued or running task.
dispatch_pendingB
Dispatch queued tasks to connected drones.
fetch_artifactC
Fetch one verified artifact to the coordinator host.
fleet_snapshotC
Get drones, capacity, and task state.
promote_persistentC
Move a drone onto an already-mounted persistent data volume.
reconcile_runningB
Reconcile running task state with connected drones.
register_droneC
Register or heartbeat a drone. ssh_user may name the SSH account or config alias user.
run_jobsC
Submit and, by default, dispatch one-shot or long-lived jobs as a batch.
stage_bundleB
Copy a local script or directory to one drone once for reuse by many jobs.
task_artifactsC
List task artifact metadata.
task_logsC
Read bounded task logs.
task_statusC
Read one task.
user_eventC
Record a dashboard/user action for an agent.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Most tools target clearly distinct resources or actions (task_status vs task_logs vs task_artifacts, fetch_artifact vs task_artifacts). The one soft overlap is run_jobs, which 'submits and by default dispatches' jobs, versus dispatch_pending and reconcile_running, which also manage task dispatch state, creating some ambiguity about when to use each. Otherwise boundaries are clean.
All names use snake_case consistently. Action tools follow verb_noun (register_drone, cancel_task, dispatch_pending, fetch_artifact) while read tools use noun_noun (task_status, task_logs, task_artifacts, fleet_snapshot), which is a readable convention but not a single uniform pattern.
13 tools sits well within the ideal range and each maps to a real facet of drone orchestration (fleet state, registration, job submission, staging, task inspection, artifact handling, dispatch/reconcile). No obvious filler or redundancy in the count.
The surface covers a full task lifecycle: register, stage, submit, dispatch, monitor, fetch artifacts, cancel, reconcile, and promote persistence. Minor gaps exist, such as no explicit drone deregistration/removal or bulk task listing, but core workflows have no dead ends.
Related MCP Connectors
Remote shell and detached long-running jobs on your own machines — no SSH, open ports or VPN.
Develop, manage, and debug Railway projects, services, and deployments from within agents.
Your agents' cloud for individuals and teams. Search, execute, packages, jobs, and credentials.
Build, test, deploy, and operate Connic agents.
Related MCP Servers
- AlicenseAqualityCmaintenanceDurable MCP server for managing long-running jobs locally, over SSH, or on Slurm clusters. Jobs survive client disconnects and return exit codes, bounded logs, and JSON artifacts.1117 PyPI1MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to remotely execute shell commands and transfer files on SSH hosts, including jump-host tunneling, background tasks, resumable transfers, and optional approval of destructive commands, while SSH credentials remain in the local process. It runs over stdio or a streamable HTTP daemon and supports auditing, allow/deny lists, and multiple authentication methods.ISC
- AlicenseAqualityCmaintenanceEnables AI assistants to run shell commands, read, write, edit, search, and stream files on remote SSH servers and Docker containers, including nested multi-layer chains, without installing any runtime on the target hosts. It auto-injects a self-contained Go helper with adaptive zstd compression for fast transfers and process control.9MIT
- AlicenseNot gradedqualityCmaintenanceEnables an AI agent to drive a remote Linux machine over the LAN through a single TCP connection, exposing tools for shell commands, jobs, interactive PTYs, file read/write/search/transfer, process and service management, networking, packages, and power control, with optional multi-host switching. Operates without SSH or any Linux-side installation beyond one stdlib-only Python daemon, using a state-free binary protocol.MIT