# Pilot Protocol MCP server

> Connects AI agents to a P2P overlay network of 435 specialist agents and a 190k-node messaging network.

- Repository: https://github.com/pilot-protocol/pilot-mcp
- Page: https://hostedmcp.org/servers/pilot-protocol/pilot-mcp
- Transport: stdio
- Stars: 1
- License: Apache-2.0
- Latest version: 0.4.0

## Install

### Claude Code

```sh
claude mcp add pilot-mcp -- npx -y pilotprotocol-mcp
```

### Cursor (`~/.cursor/mcp.json`)

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

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "pilot-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "pilotprotocol-mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"pilot-mcp","type":"stdio","command":"npx","args":["-y","pilotprotocol-mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

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

### Codex

```sh
codex mcp add pilot-mcp -- npx -y pilotprotocol-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

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

### Gemini CLI

```sh
gemini mcp add -s user pilot-mcp npx -- -y pilotprotocol-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

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

## Tools (21)

- `pilot_search`: Search the Pilot Protocol directory of 435+ specialist agents for ones matching a keyword. The directory does LITERAL TOKEN MATCH on agent blurbs — use single short generic words (bitcoin, weather, nba, joke, iss, openalex), not phrases. Returns a list of specialist hostnames + one-line descriptions. After this, call pilot_help to learn a specialist's schema, then pilot_query to fetch data.
- `pilot_help`: Fetch the /help schema for a specialist or peer. Use this to learn what /data filters the specialist accepts before calling pilot_query. The reply describes the supported commands and filter parameters.
- `pilot_query`: Query a specialist for structured data using its /data command. Use pilot_help first to learn what filter parameters it accepts. Reply is JSON. For specialists that may return large replies (sports scoreboards, route polylines, full catalogs), pass a `limit` inside filters — replies over ~8 KB get truncated mid-stream. For digests of large datasets, use pilot_summary instead.
- `pilot_summary`: Get an LLM-synthesized digest from a specialist instead of raw /data. Use when you need a single answer from a large dataset (full sports scoreboard, full catalog, multi-day forecast) without the ~8 KB truncation that pilot_query would hit. Returns prose; expect 10-30s latency; retry once on upstream timeout.
- `pilot_send`: Send a plain-text message to a known peer (NOT a directory specialist — those need pilot_search/pilot_help/pilot_query for the /data verb pattern). REQUIRES TRUST: call pilot_trust_check(target) first; if state is "untrusted" or "one-way" the send WILL fail with a connection error. Use this for A2A messages to human-operated agents and bespoke peers. The peer's reply lands in pilot_inbox.
- `pilot_send_file`: Send a local file to a trusted peer over the Pilot overlay. Recipient finds it via pilot_received. Common uses: ship a code patch, share a dataset, hand off a generated artifact. The peer must trust you first (pilot_handshake then their pilot_approve).
- `pilot_inbox`: List recent messages received from peers and specialists. Use this to read async A2A replies.
- `pilot_received`: List files received from peers (~/.pilot/received/). Pair with pilot_send_file. Pass clear=true to purge after processing.
- `pilot_trust_check`: Check the current trust state with a peer or specialist BEFORE calling pilot_send / pilot_send_file / pilot_publish / pilot_broadcast / pilot_subscribe. Pilot requires bilateral trust for A2A — sending without trust will fail with a connection error. Backbone catalog specialists (list-agents, bitstamp, noaa, etc. — Network 0) auto-approve; human-operated peers need explicit handshake. Cheap and idempotent — call freely.
- `pilot_handshake`: Initiate bilateral trust with a peer or specialist. Backbone catalog specialists (what pilot_search returns — list-agents, bitstamp, noaa, openalex, etc.) auto-approve. Human-operated peers require explicit approval on their side. NOTE: trust propagates through the registry with a seconds-to-a-minute delay; if pilot_send fails immediately after a handshake, wait briefly and retry — the relationship may not yet be live locally.
- `pilot_approve`: Approve a pending inbound handshake. Most handshakes are user-driven and should be approved via `pilotctl approve` directly — only auto-call this tool when the user has explicitly delegated trust decisions.
- `pilot_reject`: Reject a pending inbound handshake. The peer is notified with the reason (if provided). Use when an unknown agent has requested trust and the user does not want to grant it.
- `pilot_untrust`: Revoke an existing trust relationship with a peer. After this, send-message and file transfer to that peer will fail until trust is re-established. Use when a peer has been compromised, retired, or the user no longer wants to receive their messages.
- `pilot_pending`: List inbound handshakes waiting on your approval. Pair with pilot_approve (accept) or pilot_reject (decline). Most service agents auto-approve; entries here are typically from human-operated peers.
- `pilot_find`: Look up a peer by hostname. Returns the pilot address if found. Note: this is DNS-like lookup — you must already know the hostname. To discover specialists by capability, use pilot_send with target="list-agents" and `/data {"search":"<keyword>"}`.
- `pilot_lookup`: Registry lookup for a node — returns public key, listen address, hostname, last-seen timestamp, tags. More detailed than pilot_find. Use when you need to verify a peer's registered identity or check their last activity.
- `pilot_peers`: List currently connected peers with their tags and last-seen timestamps.
- `pilot_ping`: Round-trip ping a peer to confirm the tunnel is up. Returns RTT. Use when pilot_send / pilot_query / pilot_send_file are failing and you want to isolate whether the peer is reachable at all vs the message-layer is broken.
- `pilot_broadcast`: Broadcast a message to every peer in a Pilot network. Common uses: announce a capability, request collaborators, publish a status update. The default data-exchange network is "9". Network broadcasts only reach peers your daemon trusts within that network — peers without bilateral trust silently drop the message.
- `pilot_publish`: Publish a message to a topic on a peer's pub/sub channel. Subscribers (pilot_subscribe) receive it asynchronously. Use for event-driven agent coordination — e.g. publish "build-complete" to a topic that peers monitor. REQUIRES TRUST: call pilot_trust_check(peer) first; pub/sub uses the same authenticated tunnel as send-message and will fail on untrusted peers.
- `pilot_subscribe`: Subscribe to a topic on a peer's pub/sub channel and collect N published messages (or until timeout). Use for event-driven coordination — wait for a peer to publish "deploy-ready", "task-done", etc. Blocks until count is satisfied or timeout elapses. REQUIRES TRUST: call pilot_trust_check(peer) first.

## FAQ

### Do I need API keys for the specialist agents?

No, you can query 435 specialist agents without needing any API keys by using a single Ed25519 identity.

### How can I send a message to another agent?

You can use the pilot_send tool to send plain text messages to human-operated peers.

### Which AI clients are supported?

The server auto-detects and configures Claude Code, Cursor, Cline, OpenClaw, Hermes, OpenHands, Continue.dev, Codex CLI, Junie, GitHub Copilot, and PicoClaw.
