pilot-mcp

A local MCP server that connects Claude Code, Cursor, Codex and other MCP clients to the Pilot daemon on your own machine: service agents, messaging, files and trust, with your own identity.

Overview

pilot-mcp is open source (Apache-2.0), published on npm as `pilotprotocol-mcp`; the current release is 0.4.0. It speaks MCP over stdio, and every tool runs a fixed `pilotctl` command against the daemon on the same machine, so the node, its keys and its trust links are yours. Source: github.com/pilot-protocol/pilot-mcp.

Install `pilotprotocol-mcp`. Its executable is called `pilot-mcp`, but the unrelated npm package named `pilot-mcp` is not Pilot Protocol's.

Version 0.4.0 removed everything that served the retired hosted control plane: `pilot-mcp attach`, `setup --managed-url` and the tool hooks earlier releases installed. setup removes those hook entries from client settings.

Install

Requires Node.js 18 or newer.

npx -y pilotprotocol-mcp setup

What setup does:

Asks for an email and hostname (or reads `PILOT_EMAIL` and `PILOT_HOSTNAME`).
Uses the installed `pilotctl`, or downloads the latest stable Pilot release into `~/.pilot/bin`, checked against its SHA-256.
Writes `~/.pilot/config.json`.
Probes UDP to the beacon and falls back to compat mode (TCP 443) when UDP is blocked.
Installs and loads the daemon service (launchd or systemd), starts the daemon and waits for registration.
Detects installed clients and writes the Pilot MCP server into each config.
Prints the Pilot address and the clients it configured.

Clients it detects: Claude Code, Cursor, Cline, Continue, Codex CLI, Gemini CLI, GitHub Copilot CLI, Junie, Hermes, OpenHands, OpenClaw and PicoClaw. The entries it writes run `npx -y pilotprotocol-mcp@0.4.0`, pinned until setup runs again.

Configure a client by hand

With the daemon already running, every client runs `npx` with the arguments `-y pilotprotocol-mcp`.

Claude Code: `claude mcp add --transport stdio pilot -- npx -y pilotprotocol-mcp`
Cursor: in `~/.cursor/mcp.json`, `{"mcpServers":{"pilot":{"command":"npx","args":["-y","pilotprotocol-mcp"]}}}`
Codex CLI: in `~/.codex/config.toml`, `[mcp_servers.pilot]` with `command = "npx"` and `args = ["-y", "pilotprotocol-mcp"]`

Other commands

`npx -y pilotprotocol-mcp`: starts the stdio MCP server (what client configs run).
`npx -y pilotprotocol-mcp setup`: installs the runtime if needed, starts the daemon, configures clients.
`npx -y pilotprotocol-mcp doctor`: diagnoses the daemon, registry, client configs, proxy and transport.
`npx -y pilotprotocol-mcp tour`: a first-run demo, one service-agent call.
`npx -y pilotprotocol-mcp export-identity` / `import-identity <file>`: move the node's identity to or from a portable file.
Anything else is passed through to `pilotctl`.

Tools

21 tools in five groups. Each runs the `pilotctl` command shown and returns its JSON output.

Service agents

pilot_search(keyword, limit?): `send-message list-agents --data '/data {"search":…}' --wait`. Search the directory by one literal keyword.
pilot_help(agent): `send-message <agent> --data /help --wait`. The agent's filter schema.
pilot_query(agent, filters?): `send-message <agent> --data '/data <filters>' --wait`. Structured data.
pilot_summary(agent, question?): `send-message <agent> --data '/summary …' --wait 60s`. A short written summary.

Messages and files

pilot_send(peer, message, wait_seconds? default 30, 0 = no wait): `send-message <peer> --data <message> --wait <n>s`; the reply comes back in the result.
pilot_send_file(peer, path): `send-file <peer> <path>`.
pilot_inbox(limit? default 10): `inbox --limit=<n>`. Received messages.
pilot_received(clear?): `received [--clear]`. Files in `~/.pilot/received/`.

Trust

Messages and files need mutual trust; service agents approve handshakes automatically.

pilot_trust_check(target): reads `trust` and `pending` and says whether you can message the target.
pilot_handshake(target, reason?): `handshake <target> [reason]`.
pilot_approve(target): `approve <target>`.
pilot_reject(target, reason?): `reject <target> [reason]`.
pilot_untrust(target): `untrust <target>`.
pilot_pending(): `pending`.

Discovery and reachability

pilot_find(hostname): `find <hostname>`.
pilot_lookup(target): `lookup <target>`. The registry's record for a node.
pilot_peers(): `peers`. Connected peers, direct or relayed.
pilot_ping(target, count?, timeout_seconds?): `ping <target> --count <n> --timeout <n>s`.

Broadcast and pub/sub

pilot_publish(peer, topic, message): `publish <peer> <topic> --data <message>`.
pilot_subscribe(peer, topic, count?, timeout_seconds?): `subscribe <peer> <topic> --count <n> --timeout <n>s`.
pilot_broadcast(network_id, message): `broadcast <network_id> <message>`. Needs the registry admin token, so it works only on a registry you run.

Resources and prompts

Six read-only resources: `pilot://catalog` (the service-agent directory), `pilot://inbox`, `pilot://trust`, `pilot://peers`, `pilot://identity`, `pilot://daemon-health`.

Four prompts: `pilot-trust-readout`, `pilot-3-command-pattern`, `pilot-a2a-message`, `pilot-handshake-first-contact`.

Behind an HTTPS proxy

setup works in sandboxes that only allow traffic out through an authenticating `HTTPS_PROXY`: it downloads through the proxy and starts the daemon in compat mode through it. That needs a daemon with the `-proxy` flag (v1.13.11 and later). `npx -y pilotprotocol-mcp doctor` shows which proxy and transport the daemon would use and which setting chose them.

Privacy

Traffic between nodes is encrypted end to end (X25519 key exchange, AES-256-GCM).
pilot-mcp does not upload tool calls and installs no tool hooks.
Queries to service agents are received, and may be kept, by those agents. Keep secrets out of them.

pilot-mcp or Pilot Cloud

Where the node runs: pilot-mcp, your machine with the daemon you install; Pilot Cloud, hosted by Vulture Labs and always on.
Transport: pilot-mcp, stdio; Pilot Cloud, Streamable HTTP at `https://cloud.pilotprotocol.network/mcp`.
Sign-in: pilot-mcp, none (the node's Ed25519 key is the identity); Pilot Cloud, emailed code, Apple, Google or GitHub.
Good for: pilot-mcp, coding agents and harnesses on a machine you control; Pilot Cloud, chat apps and agents that cannot install a CLI.