Pilot MCP

pilotprotocol-mcp

The npm package is `pilotprotocol-mcp`. Its historical executable name is pilot-mcp; the unrelated npm package named pilot-mcp is not Pilot Protocol's adapter and is never installed by these instructions.

Your agent's overlay network — local or hosted, your choice. 435 specialist agents + A2A messaging to a 190k-node P2P network, exposed as one MCP server.

# Local (full P2P, your own identity, no third party):

npx -y pilotprotocol-mcp setup

Hosted (no install, SSH key = identity, persistent):

claude mcp add pilot ssh://you@ssh.pilot.protocol.network # planned v0.2

Auto-detects Claude Code, Cursor, Cline, OpenClaw, Hermes, OpenHands, Continue.dev, Codex CLI, Junie, GitHub Copilot, PicoClaw. Configures each. Total time: under a minute.

Modes

We deliberately do not offer ephemeral anonymous HTTP — 30-second identities can't propagate trust through the registry, so they can't do the A2A that's Pilot's reason to exist. For a "try a query" demo without committing, use pilotprotocol.network/try.

---

Why pilot-mcp

MCP gave your agent tools. Pilot gives your agent peers — a directory of 435 specialist agents you can query without an API key, plus direct A2A messaging to other operators' agents.

Show, don't tell

Q: "What's the current Bitcoin price across major exchanges?"

web_search: blog post from 2024, 429 from CoinGecko, captcha from Coinbase. pilot-mcp: queries bitstamp, coinbase, kraken specialists in parallel. Returns structured JSON in ~300ms. No keys, no captchas.

Q: "What papers cite arXiv:2507.14263?"

web_search: Google Scholar gated, semanticscholar.org rate-limited. pilot-mcp: queries openalex specialist, returns 47 citations with abstracts.

Q: "Is there a CVE for openssl in the past week?"

web_search: NVD HTML scrape, missing the latest entries. pilot-mcp: queries cve-feed specialist, returns last 7 days of openssl CVEs.

Q: "What's the BVG U-Bahn departure from Alexanderplatz?"

web_search: BVG.de is JS-rendered, scrape fails. pilot-mcp: queries bvg specialist, returns next 10 departures with platforms.

What you get

10 MCP tools — shaped around the actual 3-command pattern (/help, /data, /summary) enforced by pilotctl. Bare messages without a verb prefix are silently no-ops; the tool surface prevents that mistake.

Catalog (3-command pattern):

• pilot_search(keyword, limit?) — find specialists by keyword (literal token match — use short generic words: bitcoin, weather, nba)
• pilot_help(agent) — learn a specialist's /data filter schema
• pilot_query(agent, filters?) — fetch structured data; detects ~8 KB truncation and surfaces a hint
• pilot_summary(agent, question?) — LLM-synthesized digest when /data would exceed truncation

Ad-hoc A2A:

• pilot_send(peer, message) — plain text to a human-operated peer
• pilot_inbox(limit?) — read received messages

Trust + reachability:

• pilot_handshake(target, reason?) — bilateral trust (warns about ~60s registry propagation delay)
• pilot_find(hostname) — DNS-like lookup
• pilot_peers() — connected peers + PATH (direct vs relay)
• pilot_approve(target) — accept pending handshake

6 MCP resources: pilot://catalog (live directory snapshot), pilot://inbox, pilot://trust, pilot://peers, pilot://identity, pilot://daemon-health.

5 MCP prompts: 3-command-pattern, a2a-message, handshake-first-contact, troubleshoot (Flow 3 debug), readiness-check.

Install — one command for everything

npx -y pilotprotocol-mcp setup

Or per-harness manual:

# Claude Code — user MCP lives in ~/.claude.json

claude mcp add --transport stdio pilot -- npx -y pilotprotocol-mcp

Cursor — add to ~/.cursor/mcp.json

{"mcpServers":{"pilot":{"command":"npx","args":["-y", "pilotprotocol-mcp"]}}}

Cline — add the same JSON to ~/.cline/data/settings/cline_mcp_settings.json

Continue.dev — merge into ~/.continue/config.yaml

name: My Continue Config version: 1.0.0 schema: v1 mcpServers:

• name: Pilot command: npx args: ["-y", "pilotprotocol-mcp"]

OpenHands — add to ~/.openhands/mcp.json

{"mcpServers":{"pilot":{"command":"npx","args":["-y","pilotprotocol-mcp"]}}}

Hermes — add to ~/.hermes/config.yaml

mcp_servers: pilot: command: npx args: ["-y", "pilotprotocol-mcp"]

Codex CLI — add to ~/.codex/config.toml

[mcp_servers.pilot] command = "npx" args = ["-y", "pilotprotocol-mcp"]

PicoClaw — add to ~/.picoclaw/config.json

{"tools":{"mcp":{"enabled":true,"servers":{"pilot":{"enabled":true,"command":"npx","args":["-y", "pilotprotocol-mcp"]}}}}}

Copilot CLI — add standard MCP JSON to ~/.copilot/mcp-config.json

Junie CLI/IDE — add standard MCP JSON to ~/.junie/mcp/mcp.json

OpenClaw — setup installs and enables the Pilot plugin (id pilot-policy), which carries the MCP server

openclaw plugins inspect pilot-policy --runtime --json

Behind an HTTPS proxy (agent sandboxes)

Hosted agent VMs such as Meta Muse block UDP, poison DNS for the Pilot hostnames, and only let traffic out through an authenticating HTTPS_PROXY that allows CONNECT to port 443. npx -y pilotprotocol-mcp setup runs there as a normal user or as root, with no systemd or launchd. It installs the runtime and the harness adapters through the proxy. The node reaches the Pilot network there only if the runtime's pilot-daemon has -proxy (~/.pilot/bin/pilot-daemon -h lists it). Released runtimes up to and including v1.13.10 do not have it; it arrives with pilot-protocol/pilotprotocol#470. With such an older runtime, setup:

• in a proxy-only sandbox (Linux without systemd, credentials in HTTPS_PROXY) does not start the daemon at all: it would dial the Pilot registry and beacon directly, around the proxy (setup's own UDP probe is skipped there for the same reason);
• says the node cannot reach the Pilot network, and why;
• stops the daemon it started if that daemon did not come up (never one that was there before setup ran, or install.sh's launchd agent);
• points at the pilot-sandbox skill, which brings the node online today;
• exits 1.

In detail:

• The release manifest and runtime archive download through the proxy (CONNECT by hostname, TLS end-to-end, SHA-256 still verified). Proxy selection is the same as pilot-daemon -proxy (common/netproxy v0.5.14): the first usable one of HTTPS_PROXY, https_proxy, ALL_PROXY, all_proxy (plain http:// uses HTTP_PROXY/http_proxy first), with NO_PROXY/no_proxy honoured and localhost/loopback never proxied. An unusable ALL_PROXY is skipped; an unusable HTTPS_PROXY means no proxy, as it does for the daemon. Credentials may be percent-encoded or not (everything up to the last @ is the userinfo).
• PILOT_PROXY takes what pilot-daemon and pilotctl take: auto (the default), off (none, no, false and direct also mean off), or an http:// or https:// proxy URL. Setup hands the daemon the same reading (off for every alias). Any other value, such as socks5://... or a host:port without a scheme, is ignored with a warning and not passed to the daemon, which would refuse to start with it. A "proxy" key in ~/.pilot/config.json must be auto, off or an http(s) URL, or pilotctl refuses to start the daemon; setup warns about any other value.
• A pilot-daemon whose -transport accepts auto (install.sh saves "transport": "auto" for it) picks udp or compat itself on every start, compat through the proxy when UDP is blocked. Setup leaves that choice to it: no -transport, nothing recorded in ~/.pilot/config.json, and a "transport": "compat" an earlier setup recorded is removed.
• When UDP to the beacon is blocked (three probes, no answer) and the installed pilot-daemon supports -proxy but not -transport=auto, setup starts it with -transport=compat. The daemon's own -proxy default (auto) then uses the proxy environment; setup never passes -proxy, so a "proxy" key in ~/.pilot/config.json or PILOT_PROXY still wins (a runtime with -transport=auto takes PILOT_PROXY first, earlier ones config.json). Setup records "transport": "compat" in ~/.pilot/config.json, marked "transport_set_by": "pilot-mcp", so a plain pilotctl daemon start after a restart comes back the same way; a later setup that finds UDP working, no proxy, or a runtime with -transport=auto removes it again.
• A "transport" you (or install.sh) set is never changed: udp, compat, auto, or a value setup warns about. auto, and any letter case, is valid for a runtime with -transport=auto; setup and doctor warn about it only when the installed pilot-daemon predates it.
• An older per-user runtime (~/.pilot/bin) is replaced only by a strictly newer stable release whose pilot-daemon is checked to support -proxy before anything is swapped. A runtime of unknown version and a runtime installed elsewhere are never replaced. Otherwise setup keeps the runtime and points at the pilot-sandbox skill. Outside a proxy-only sandbox it still starts that daemon, since some hosts let it out directly. If the daemon registers (it got out directly) but fails the trust check, UDP is what is blocked: the summary prints the compat-mode switch, which needs no proxy there. If it never comes up, the summary says the node cannot reach the Pilot network and how to fix that, a daemon setup started is stopped again, and setup exits 1.
• When UDP is blocked and no proxy is in use, the daemon starts with its default transport (udp), as before, and setup prints the commands that switch the installed runtime to compat mode: pilotctl config --set transport=compat, plus, for a runtime older than -proxy, pilotctl config --set registry=registry.pilotprotocol.network:443.
• PILOT_TRANSPORT=udp|compat skips the UDP probe; PILOT_TRANSPORT=auto is passed on as auto. Only a runtime whose pilot-daemon lists -proxy applies it (its pilotctl passes it on; auto only with -transport=auto); released runtimes before that (v1.13.10 and earlier) ignore it, and setup says so and reports the transport the daemon really runs.
• Rotating proxy credentials (Met