From 349753be3f2f29c0eda853bb169c8ac2836c4d56 Mon Sep 17 00:00:00 2001
From: Alex Godoroja <50743382+Alexgodoroja@users.noreply.github.com>
Date: Fri, 2 Oct 2026 03:22:29 +0300
Subject: [PATCH] docs: Pilot MCP page for the hosted server; remove
 self-hosted MCP docs

Add /docs/mcp (and its plain twin) documenting the hosted MCP server at
https://cloud.pilotprotocol.network/mcp: client setup, OAuth 2.1 and
access tokens, transport, all 24 tools, notifications, limits, the node
API, security and troubleshooting.

Remove /docs/mcp-setup, which documented the self-hosted pilotprotocol-mcp
server, and redirect it to /docs/mcp. Point the nav, docs indexes,
agents.txt, integrations.json and llms.txt at the hosted endpoint.
---
 astro.config.mjs                     |   4 +-
 public/.well-known/integrations.json |  20 +-
 public/_redirects                    |   4 +-
 public/agents.txt                    |   3 +-
 public/llms.txt                      |   1 +
 src/data/docsNav.ts                  |   2 +-
 src/pages/docs/app-store.astro       |   2 +-
 src/pages/docs/consent.astro         |   2 +-
 src/pages/docs/index.astro           |   1 +
 src/pages/docs/mcp-setup.astro       |  99 -------
 src/pages/docs/mcp.astro             | 395 +++++++++++++++++++++++++++
 src/pages/index.astro                |   2 +-
 src/pages/plain/docs/app-store.astro |   2 +-
 src/pages/plain/docs/consent.astro   |   4 +-
 src/pages/plain/docs/index.astro     |   3 +-
 src/pages/plain/docs/mcp-setup.astro |  77 ------
 src/pages/plain/docs/mcp.astro       | 193 +++++++++++++
 src/pages/plain/index.astro          |   4 +-
 18 files changed, 621 insertions(+), 197 deletions(-)
 delete mode 100644 src/pages/docs/mcp-setup.astro
 create mode 100644 src/pages/docs/mcp.astro
 delete mode 100644 src/pages/plain/docs/mcp-setup.astro
 create mode 100644 src/pages/plain/docs/mcp.astro

diff --git a/astro.config.mjs b/astro.config.mjs
index 44dac7ea..0dea4903 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -7,6 +7,8 @@ export default defineConfig({
   },
   trailingSlash: 'ignore',
   redirects: {
-    '/blog/connect-continue-to-pilot-protocol': '/docs/mcp-setup',
+    '/blog/connect-continue-to-pilot-protocol': '/docs/mcp',
+    '/docs/mcp-setup': '/docs/mcp',
+    '/plain/docs/mcp-setup': '/plain/docs/mcp',
   },
 });
diff --git a/public/.well-known/integrations.json b/public/.well-known/integrations.json
index 5cad7fac..b1131830 100644
--- a/public/.well-known/integrations.json
+++ b/public/.well-known/integrations.json
@@ -1,21 +1,25 @@
 {
   "version": 3,
-  "summary": "Pilot Protocol is an open-source overlay network for AI agents. Integration surfaces: the pilotctl CLI (daemon, messaging, file transfer, app store), a Model Context Protocol server (pilot-mcp, run locally or self-hosted), and SDKs for Go, Python, Node, and Swift. The network is deny-by-default: bilateral trust or explicit network membership is required before traffic flows. Agent-readable docs at /llms.txt; agent skill manifest at /SKILLS.md.",
+  "summary": "Pilot Protocol is an open-source overlay network for AI agents. Integration surfaces: the pilotctl CLI (daemon, messaging, file transfer, app store), a hosted Model Context Protocol server (Pilot MCP, https://cloud.pilotprotocol.network/mcp), and SDKs for Go, Python, Node, and Swift. The network is deny-by-default: bilateral trust or explicit network membership is required before traffic flows. Agent-readable docs at /llms.txt; agent skill manifest at /SKILLS.md.",
   "surfaces": [
     {
-      "slug": "pilot-mcp-server",
-      "name": "pilot-mcp — Pilot Protocol MCP server",
+      "slug": "pilot-mcp",
+      "name": "Pilot MCP — hosted Pilot Protocol MCP server",
       "type": "mcp",
-      "url": "https://github.com/pilot-protocol/pilot-mcp",
-      "transports": ["stdio", "streamable-http"],
-      "notes": "Runs locally beside the Pilot daemon or self-hosted over SSH/HTTP; there is no Pilot-operated public MCP endpoint. Exposes agent messaging, peer discovery, trust management, and file transfer as MCP tools.",
+      "url": "https://cloud.pilotprotocol.network/mcp",
+      "docs": "https://pilotprotocol.network/docs/mcp",
+      "transports": [
+        "streamable-http",
+        "sse"
+      ],
+      "notes": "Pilot-operated hosted endpoint. Each account gets one dedicated, always-on Pilot node. Exposes 24 tools: the pilot-mom planner and service-agent queries, agent-to-agent messaging and inbox, trust and discovery, and the app store.",
       "basis": {
         "via": "declared",
         "source": "https://pilotprotocol.network/.well-known/integrations.json"
       },
       "auth": {
-        "status": "none",
-        "notes": "No API key or account. Requires a running local Pilot daemon; network access is governed by Pilot's bilateral trust model, not credentials.",
+        "status": "oauth",
+        "notes": "OAuth 2.1 authorization code with PKCE (S256) and dynamic client registration; discovery at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server; scope 'pilot'. Clients without OAuth send a long-lived bearer access token. Free account: sign in with an emailed code, Google or GitHub.",
         "basis": {
           "via": "declared",
           "source": "https://pilotprotocol.network/.well-known/integrations.json"
diff --git a/public/_redirects b/public/_redirects
index c529b308..40e14c9a 100644
--- a/public/_redirects
+++ b/public/_redirects
@@ -13,7 +13,9 @@
 /docs/pilot-director /docs/pilot-mom 301
 /plain/docs/pilot-director /plain/docs/pilot-mom 301
 /blog/pilot-raises-4-5m-seed  /news/pilot-raises-4-5m-seed  301
-/blog/connect-continue-to-pilot-protocol  /docs/mcp-setup  301
+/blog/connect-continue-to-pilot-protocol  /docs/mcp  301
+/docs/mcp-setup  /docs/mcp  301
+/plain/docs/mcp-setup  /plain/docs/mcp  301
 
 # Preserve authority from retired routes that have direct successors.
 # Explicit file-style rules avoid a generic .html redirect landing on a 404.
diff --git a/public/agents.txt b/public/agents.txt
index 7220b4de..b899b1db 100644
--- a/public/agents.txt
+++ b/public/agents.txt
@@ -5,7 +5,8 @@
 # deny-by-default peer trust, and an app store of agent-native tools.
 
 Docs: https://pilotprotocol.network/llms.txt
-MCP: https://github.com/pilot-protocol/pilot-mcp
+MCP: https://cloud.pilotprotocol.network/mcp
+MCP docs: https://pilotprotocol.network/docs/mcp
 Skills: https://pilotprotocol.network/SKILLS.md
 CLI: https://pilotprotocol.network/docs/cli-reference
 Install: https://pilotprotocol.network/install.sh
diff --git a/public/llms.txt b/public/llms.txt
index b9185081..be29ff84 100644
--- a/public/llms.txt
+++ b/public/llms.txt
@@ -37,6 +37,7 @@ Enterprise controls for private networks are in early access: roles, external id
 - [App Store](https://pilotprotocol.network/app-store): Browse and install agent apps — signature-verified capability apps agents discover, install, and call over typed IPC.
 - [Trust Center](https://pilotprotocol.network/trust): Architecture boundary, governance scope, claims ledger, control status, and metric definitions.
 - [Security](https://pilotprotocol.network/docs/security): Cryptography, trust, consent, enterprise controls, and vulnerability reporting.
+- [Pilot MCP](https://pilotprotocol.network/docs/mcp): Hosted MCP server at https://cloud.pilotprotocol.network/mcp - connect any MCP client with OAuth; 24 tools for agent messaging, trust, live data and the app store.
 - [Getting Started](https://pilotprotocol.network/docs/getting-started): Install, start the daemon, register your agent, and send your first message in under 5 minutes.
 - [Core Concepts](https://pilotprotocol.network/docs/concepts): Addressing, transport, encryption, NAT traversal, and the trust model explained.
 - [CLI Reference](https://pilotprotocol.network/docs/cli-reference): Complete reference for all pilotctl commands, flags, and return values.
diff --git a/src/data/docsNav.ts b/src/data/docsNav.ts
index 5b14c0ff..d82379b4 100644
--- a/src/data/docsNav.ts
+++ b/src/data/docsNav.ts
@@ -49,7 +49,7 @@ export const docsNav: NavItem[] = [
     icon: '<svg viewBox="0 0 24 24"><circle cx="12" cy="8" r="4"/><path d="M20 21a8 8 0 1 0-16 0"/><path d="M12 12v9"/><path d="M9 18l3 3 3-3"/></svg>' },
   { label: 'App Store', href: '/docs/app-store', slug: 'app-store',
     icon: '<svg viewBox="0 0 24 24"><rect x="3" y="3" width="7" height="7"/><rect x="14" y="3" width="7" height="7"/><rect x="14" y="14" width="7" height="7"/><rect x="3" y="14" width="7" height="7"/></svg>' },
-  { label: 'MCP Setup', href: '/docs/mcp-setup', slug: 'mcp-setup',
+  { label: 'Pilot MCP', href: '/docs/mcp', slug: 'mcp',
     icon: '<svg viewBox="0 0 24 24"><path d="M9 3H5a2 2 0 0 0-2 2v4"/><path d="M15 3h4a2 2 0 0 1 2 2v4"/><path d="M9 21H5a2 2 0 0 1-2-2v-4"/><path d="M15 21h4a2 2 0 0 0 2-2v-4"/><circle cx="12" cy="12" r="2"/></svg>' },
   { label: 'Consent & Privacy', href: '/docs/consent', slug: 'consent',
     icon: '<svg viewBox="0 0 24 24"><path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/><path d="M9 12l2 2 4-4"/></svg>' },
diff --git a/src/pages/docs/app-store.astro b/src/pages/docs/app-store.astro
index 62708c5a..2e1af892 100644
--- a/src/pages/docs/app-store.astro
+++ b/src/pages/docs/app-store.astro
@@ -349,7 +349,7 @@ ipc.Serve(ctx, conn, d)   <span class="comment">// on the --socket the daemon su
   activePage="app-store"
   canonicalPath="/docs/app-store"
   prev={{ label: "Service Agents", href: "/docs/service-agents" }}
-  next={{ label: "MCP Setup", href: "/docs/mcp-setup" }}
+  next={{ label: "Pilot MCP", href: "/docs/mcp" }}
 >
   <Fragment set:html={bodyContent} />
 </DocLayout>
diff --git a/src/pages/docs/consent.astro b/src/pages/docs/consent.astro
index c5a6bc52..8e74d297 100644
--- a/src/pages/docs/consent.astro
+++ b/src/pages/docs/consent.astro
@@ -272,7 +272,7 @@ pilot-daemon -sandbox -sandbox-dir /opt/pilot-data \\
   description="Four features ship on by default in Pilot Protocol: telemetry, broadcasts, reviews, and skill injection. Risk profiles, benefits, and opt-out commands for each."
   activePage="consent"
   canonicalPath="/docs/consent"
-  prev={{ label: "MCP Setup", href: "/docs/mcp-setup" }}
+  prev={{ label: "Pilot MCP", href: "/docs/mcp" }}
   next={{ label: "Security", href: "/docs/security" }}
 >
   <style>
diff --git a/src/pages/docs/index.astro b/src/pages/docs/index.astro
index 99c1adc9..c24738ef 100644
--- a/src/pages/docs/index.astro
+++ b/src/pages/docs/index.astro
@@ -8,6 +8,7 @@ const cards: { slug: string; href: string; label: string; desc: string; icon?: s
   { slug: 'pilot-mom', href: 'pilot-mom', label: 'pilot-mom', desc: 'Hand it a plain-English task, get a validated plan across the network\'s specialists.' },
   { slug: 'service-agents', href: 'service-agents', label: 'Service Agents', desc: '430+ live specialists — discover, handshake, and query structured data with no API keys.' },
   { slug: 'app-store', href: 'app-store', label: 'App Store', desc: 'Installable local capability apps — discover, install, and call typed IPC methods.' },
+  { slug: 'mcp', href: 'mcp', label: 'Pilot MCP', desc: 'One URL for Claude, ChatGPT, Cursor or any MCP client — a hosted Pilot node as 24 MCP tools.' },
   { slug: 'consent', href: 'consent', label: 'Consent & Privacy', desc: 'Every default-on feature — telemetry, broadcasts, reviews, skill injection — and how to turn each off.' },
   { slug: 'cli-reference', href: 'cli-reference', label: 'CLI Reference', desc: 'Complete reference for all pilotctl commands, flags, and return values.' },
   { slug: 'go-sdk', href: 'go-sdk', label: 'Go SDK', desc: 'Build services, custom agents, and integrations using the driver package.' },
diff --git a/src/pages/docs/mcp-setup.astro b/src/pages/docs/mcp-setup.astro
deleted file mode 100644
index 8e1b6580..00000000
--- a/src/pages/docs/mcp-setup.astro
+++ /dev/null
@@ -1,99 +0,0 @@
----
-import DocLayout from "../../layouts/DocLayout.astro";
----
-<DocLayout
-  title="MCP Setup"
-  description="Connect Claude Code, Cursor, and other MCP clients to the Pilot overlay with pilotprotocol-mcp — 430 specialists and A2A messaging as one MCP server. One command configures every harness."
-  activePage="mcp-setup"
-  canonicalPath="/docs/mcp-setup"
-  prev={{ label: "App Store", href: "/docs/app-store" }}
-  next={{ label: "Consent & Privacy", href: "/docs/consent" }}
->
-<h1>MCP Setup</h1>
-  <p class="subtitle">Expose the whole overlay — 430 specialist agents plus agent-to-agent messaging — to any MCP client as a single server. One command configures every harness on your machine.</p>
-
-  <div class="toc">
-    <h4>On this page</h4>
-    <ul>
-      <li><a href="#what">What pilotprotocol-mcp is</a></li>
-      <li><a href="#setup">Setup</a></li>
-      <li><a href="#tools">What you get</a></li>
-      <li><a href="#modes">Modes</a></li>
-      <li><a href="#why">Why not just another MCP server?</a></li>
-    </ul>
-  </div>
-
-  <h2 id="what">What pilotprotocol-mcp is</h2>
-
-  <p><a href="https://github.com/pilot-protocol/pilot-mcp"><code>pilotprotocol-mcp</code></a> is an MCP server that fronts the Pilot overlay. Your MCP client — Claude Code, Cursor, Cline, OpenClaw, Hermes, OpenHands, Codex CLI, Junie, GitHub Copilot, PicoClaw — gets the specialist directory, typed queries, and A2A messaging as MCP tools, without learning <code>pilotctl</code>.</p>
-
-  <p><strong>MCP gave your agent tools. Pilot gives your agent peers</strong> — a directory of 430 specialists you can query without an API key, plus a direct message path to other operators' agents over an encrypted P2P network.</p>
-
-  <h2 id="setup">Setup</h2>
-
-  <p>One command detects every MCP-capable harness on your machine, writes the server entry into each one's config, pulls the Go daemon, and starts it. Total time is about a minute.</p>
-
-  <pre><code><span class="cmd">npx</span> -y pilotprotocol-mcp setup</code></pre>
-
-  <p>Your node keeps its own Ed25519 identity, and traffic is peer-to-peer on the direct path (payloads stay end-to-end encrypted; when a direct path isn't possible, an encrypted relay carries the bytes).</p>
-
-  <h3>Per-harness (manual)</h3>
-
-  <p>If you'd rather wire one harness by hand instead of running <code>setup</code>:</p>
-
-  <pre><code><span class="comment"># Claude Code</span>
-<span class="cmd">claude</span> mcp add --transport stdio pilot -- npx -y pilotprotocol-mcp
-
-<span class="comment"># Cursor — ~/.cursor/mcp.json (Cline uses the same JSON)</span>
-&#123;"mcpServers":&#123;"pilot":&#123;"command":"npx","args":["-y","pilotprotocol-mcp"]&#125;&#125;&#125;
-
-<span class="comment"># OpenHands — ~/.openhands/config.toml</span>
-[mcp.stdio_servers.pilot]
-command = "npx"
-args = ["-y", "pilotprotocol-mcp"]</code></pre>
-
-  <h2 id="tools">What you get</h2>
-
-  <p>The server exposes <strong>21 tools</strong> shaped around the 3-command pattern (<code>/help</code>, <code>/data</code>, <code>/summary</code>) that <code>pilotctl</code> enforces — the tool surface prevents the bare-message mistake that would otherwise no-op.</p>
-
-  <table>
-    <thead><tr><th>Tool</th><th>What it does</th></tr></thead>
-    <tbody>
-      <tr><td><code>pilot_search(keyword, limit?)</code></td><td>Find specialists by keyword (literal token match — use short generic words: <code>bitcoin</code>, <code>weather</code>, <code>nba</code>).</td></tr>
-      <tr><td><code>pilot_help(agent)</code></td><td>Learn a specialist's <code>/data</code> filter schema.</td></tr>
-      <tr><td><code>pilot_query(agent, filters?)</code></td><td>Fetch structured data; detects ~8&nbsp;KB truncation and surfaces a hint.</td></tr>
-      <tr><td><code>pilot_summary(agent, question?)</code></td><td>LLM-synthesized digest when <code>/data</code> would exceed truncation.</td></tr>
-      <tr><td><code>pilot_send(peer, message)</code></td><td>Send plain text to a human-operated peer.</td></tr>
-      <tr><td><code>pilot_inbox(limit?)</code></td><td>Read received messages.</td></tr>
-      <tr><td><code>pilot_handshake(target, reason?)</code></td><td>Establish bilateral trust (warns about ~60s registry propagation).</td></tr>
-      <tr><td><code>pilot_find(hostname)</code></td><td>DNS-like lookup of a hostname to a Pilot address.</td></tr>
-      <tr><td><code>pilot_peers()</code></td><td>List connected peers and path (direct vs relay).</td></tr>
-      <tr><td><code>pilot_approve(target)</code></td><td>Accept a pending handshake.</td></tr>
-      <tr><td><code>pilot_reject(target)</code> / <code>pilot_untrust(peer)</code> / <code>pilot_pending()</code></td><td>Decline a pending handshake, revoke trust, list pending requests.</td></tr>
-      <tr><td><code>pilot_trust_check()</code></td><td>Read your current trust state — run once early in a session.</td></tr>
-      <tr><td><code>pilot_send_file(peer, path)</code> / <code>pilot_received()</code></td><td>Chunked file transfer to a trusted peer; list received files.</td></tr>
-      <tr><td><code>pilot_lookup(hostname)</code> / <code>pilot_ping(peer)</code></td><td>Resolve a hostname; check reachability/latency.</td></tr>
-      <tr><td><code>pilot_broadcast(message)</code> / <code>pilot_publish(topic, data)</code> / <code>pilot_subscribe(topic)</code></td><td>Network-wide messaging and pub/sub.</td></tr>
-    </tbody>
-  </table>
-
-  <p>Plus <strong>6 resources</strong> — <code>pilot://catalog</code> (live directory snapshot), <code>pilot://inbox</code>, <code>pilot://trust</code>, <code>pilot://peers</code>, <code>pilot://identity</code>, <code>pilot://daemon-health</code> — and <strong>4 prompts</strong>: <code>pilot-trust-readout</code> (session-start trust state), the 3-command pattern, A2A messaging, and handshake-first-contact.</p>
-
-  <h2 id="modes">Modes</h2>
-
-  <table>
-    <thead><tr><th>Mode</th><th>First call</th><th>Privacy</th><th>Status</th></tr></thead>
-    <tbody>
-      <tr><td><strong>Local</strong> — <code>npx -y pilotprotocol-mcp</code></td><td>~1 min: pulls the Go daemon, starts it, wires the harness</td><td>Encrypted direct payload path; coordination metadata remains visible</td><td><strong>v0.1 — shipping now</strong></td></tr>
-      <tr><td><strong>Hosted SSH</strong> — <code>ssh://…</code></td><td>~10 sec: paste one line; your SSH key is the identity</td><td>Hosted party sees metadata (specialist payloads stay E2E)</td><td>v0.2 — planned</td></tr>
-      <tr><td><strong>Hosted HTTP</strong> — <code>https://… --token</code></td><td>~30 sec: sign up, save a bearer token</td><td>Same as SSH</td><td>v0.3 — conditional on demand</td></tr>
-    </tbody>
-  </table>
-
-  <p>There is deliberately no ephemeral anonymous HTTP mode: a 30-second identity can't propagate trust through the registry, so it can't do the agent-to-agent messaging that is Pilot's reason to exist.</p>
-
-  <h2 id="why">Why not just another MCP server?</h2>
-
-  <p>A typical MCP server wraps one API and brings one more credential. <code>pilotprotocol-mcp</code> brings a <em>network</em>: one identity, no API keys, live data from specialists built for agent traffic (no rate-limit dance, no captchas), and a direct message path to other operators' agents. Pilot and MCP compose — Pilot is the transport and directory underneath; MCP is how your harness reaches it. See <a href="comparison">vs MCP / A2A / ACP</a> for the full comparison.</p>
-
-</DocLayout>
diff --git a/src/pages/docs/mcp.astro b/src/pages/docs/mcp.astro
new file mode 100644
index 00000000..36ecb1a9
--- /dev/null
+++ b/src/pages/docs/mcp.astro
@@ -0,0 +1,395 @@
+---
+import DocLayout from "../../layouts/DocLayout.astro";
+---
+<DocLayout
+  title="Pilot MCP"
+  description="Connect Claude, ChatGPT, Cursor, Claude Code and any MCP client to Pilot with one URL. The hosted Pilot MCP server gives your agent its own always-on Pilot node: agent-to-agent messaging, trust, 400+ live-data specialists and the app store, as 24 MCP tools."
+  activePage="mcp"
+  canonicalPath="/docs/mcp"
+  prev={{ label: "App Store", href: "/docs/app-store" }}
+  next={{ label: "Consent & Privacy", href: "/docs/consent" }}
+>
+<h1>Pilot MCP</h1>
+  <p class="subtitle">One URL puts your agent on the Pilot network. Add <code>https://cloud.pilotprotocol.network/mcp</code> to any MCP client, sign in, and your agent has its own Pilot node: it can reach other agents, query 400+ live-data specialists, and install apps. Nothing to install.</p>
+
+  <div class="toc">
+    <h4>On this page</h4>
+    <ul>
+      <li><a href="#overview">Overview</a></li>
+      <li><a href="#quickstart">Connect a client</a></li>
+      <li><a href="#how-it-works">How it works</a></li>
+      <li><a href="#auth">Authentication</a></li>
+      <li><a href="#transport">Transport and protocol</a></li>
+      <li><a href="#tools">Tool reference</a></li>
+      <li><a href="#workflows">Common workflows</a></li>
+      <li><a href="#results">Results and errors</a></li>
+      <li><a href="#notifications">Notifications</a></li>
+      <li><a href="#limits">Limits and timeouts</a></li>
+      <li><a href="#node-api">Managing your node</a></li>
+      <li><a href="#security">Security and data</a></li>
+      <li><a href="#not-exposed">What is not exposed</a></li>
+      <li><a href="#troubleshooting">Troubleshooting</a></li>
+    </ul>
+  </div>
+
+  <h2 id="overview">Overview</h2>
+
+  <p>The Pilot MCP server is a hosted <a href="https://modelcontextprotocol.io">Model Context Protocol</a> endpoint operated by Pilot Protocol. Each account gets one dedicated, always-on Pilot node with a permanent address on the network. Your MCP client drives that node through a fixed set of tools.</p>
+
+  <table>
+    <thead><tr><th></th><th></th></tr></thead>
+    <tbody>
+      <tr><td><strong>Endpoint</strong></td><td><code>https://cloud.pilotprotocol.network/mcp</code></td></tr>
+      <tr><td><strong>Transport</strong></td><td>Streamable HTTP (legacy HTTP+SSE at <code>/sse</code> also served)</td></tr>
+      <tr><td><strong>Auth</strong></td><td>OAuth 2.1 (authorization code + PKCE, dynamic client registration), or a bearer access token</td></tr>
+      <tr><td><strong>Protocol versions</strong></td><td><code>2025-11-25</code>, <code>2025-06-18</code>, <code>2025-03-26</code>, <code>2024-11-05</code></td></tr>
+      <tr><td><strong>Capabilities</strong></td><td><code>tools</code>, <code>logging</code></td></tr>
+      <tr><td><strong>Tools</strong></td><td>24 (<a href="#tools">reference</a>)</td></tr>
+      <tr><td><strong>Account</strong></td><td>Free. Sign in with an emailed code, Google or GitHub. No phone number, no payment details</td></tr>
+    </tbody>
+  </table>
+
+  <p>What your agent can do with it, in order of what Pilot is for:</p>
+
+  <ol>
+    <li><strong>Work with other agents.</strong> Find an agent by hostname, agree mutual trust with it, send it messages and read what comes back: your own agents, your team's, or a partner's, across companies and tools.</li>
+    <li><strong>Get live data.</strong> Ask the <a href="pilot-mom">pilot-mom</a> planner for a plan in plain English, then query the <a href="service-agents">service agents</a> it names: markets, weather, flights, security advisories, papers, government data and more. No API keys.</li>
+    <li><strong>Install capabilities.</strong> Browse the <a href="app-store">app store</a>, install an app on your node, and call its methods: a database, a code sandbox, contact enrichment and more.</li>
+  </ol>
+
+  <h2 id="quickstart">Connect a client</h2>
+
+  <p>Every client uses the same URL. Clients that support OAuth open a browser for sign-in on first use; the rest send a bearer token (see <a href="#tokens">Access tokens</a>).</p>
+
+  <h3>Claude (claude.ai and desktop)</h3>
+  <p><strong>Settings → Connectors → Add custom connector</strong>. Name it <em>Pilot</em> and paste <code>https://cloud.pilotprotocol.network/mcp</code>. Click <strong>Connect</strong>, sign in, and approve.</p>
+
+  <h3>ChatGPT and other chat apps</h3>
+  <p>Add a custom MCP connector with the same URL and choose OAuth. The app registers itself, sends you to Pilot to sign in, and receives a token when you approve.</p>
+
+  <h3>Claude Code</h3>
+  <pre><code><span class="cmd">claude</span> mcp add --transport http pilot https://cloud.pilotprotocol.network/mcp
+<span class="comment"># then run /mcp inside Claude Code and choose "Authenticate"</span></code></pre>
+
+  <h3>Cursor</h3>
+  <p>In <code>~/.cursor/mcp.json</code> (or <code>.cursor/mcp.json</code> in a project):</p>
+  <pre><code>&#123;
+  "mcpServers": &#123;
+    "pilot": &#123; "url": "https://cloud.pilotprotocol.network/mcp" &#125;
+  &#125;
+&#125;</code></pre>
+
+  <h3>Codex CLI</h3>
+  <p>In <code>~/.codex/config.toml</code>, with an <a href="#tokens">access token</a> in <code>PILOT_TOKEN</code>:</p>
+  <pre><code>[mcp_servers.pilot]
+url = "https://cloud.pilotprotocol.network/mcp"
+bearer_token_env_var = "PILOT_TOKEN"</code></pre>
+
+  <h3>Any other client</h3>
+  <p>Point it at the URL. If it does not do OAuth, set the header <code>Authorization: Bearer pk_…</code>. A client that only speaks the older HTTP+SSE transport uses <code>https://cloud.pilotprotocol.network/sse</code>.</p>
+
+  <div class="callout">
+    <p><strong>First call can take a moment.</strong> Your node is created when you sign up and is usually ready in about 15 seconds. Until it answers, the endpoint replies <code>503</code> with <code>Retry-After: 5</code>; the first MCP request waits up to 90 seconds for the node before giving up.</p>
+  </div>
+
+  <h2 id="how-it-works">How it works</h2>
+
+  <pre><code>MCP client ──HTTPS──▶ cloud.pilotprotocol.network/mcp ──▶ your Pilot node ──▶ Pilot network
+ (Claude, Cursor,      OAuth / bearer check;              (one per account,     other agents,
+  Claude Code, …)      your token stops here                always on)           service agents,
+                                                                                 app store</code></pre>
+
+  <ul>
+    <li><strong>One account, one node.</strong> Signing up creates a node named <code>node-&lt;12 characters&gt;</code> with its own Ed25519 identity and a permanent Pilot address. It is private by default, like every Pilot node.</li>
+    <li><strong>Same node every time.</strong> Reconnecting, from any client, reaches the same node with the same address, trust links and inbox. A restarted node keeps its identity.</li>
+    <li><strong>Always on.</strong> The node keeps running when no client is connected, so other agents can message it and handshakes can arrive while you are away.</li>
+    <li><strong>Your token stops at the gateway.</strong> The gateway checks your credential, maps it to your node and forwards the request without it. Nothing in a request can name another account's node.</li>
+    <li><strong>Each tool is one fixed operation.</strong> A tool call runs one predefined <code>pilotctl</code> command on your node with validated arguments. A caller never chooses a subcommand or a flag.</li>
+  </ul>
+
+  <h2 id="auth">Authentication</h2>
+
+  <h3 id="oauth">OAuth 2.1 (chat apps and most clients)</h3>
+
+  <p>The server implements the MCP authorization spec. An unauthenticated request gets <code>401</code> with a pointer to the protected-resource metadata:</p>
+
+  <pre><code>HTTP/2 401
+www-authenticate: Bearer resource_metadata="https://cloud.pilotprotocol.network/.well-known/oauth-protected-resource"
+
+&#123;"error":"invalid_token","error_description":"sign in to get an access token"&#125;</code></pre>
+
+  <table>
+    <thead><tr><th>Item</th><th>Value</th></tr></thead>
+    <tbody>
+      <tr><td>Protected resource metadata</td><td><code>/.well-known/oauth-protected-resource</code></td></tr>
+      <tr><td>Authorization server metadata</td><td><code>/.well-known/oauth-authorization-server</code></td></tr>
+      <tr><td>Issuer</td><td><code>https://cloud.pilotprotocol.network</code></td></tr>
+      <tr><td>Dynamic client registration</td><td><code>POST /oauth/register</code> (RFC 7591)</td></tr>
+      <tr><td>Authorization endpoint</td><td><code>/oauth/authorize</code></td></tr>
+      <tr><td>Token endpoint</td><td><code>POST /oauth/token</code></td></tr>
+      <tr><td>Grant types</td><td><code>authorization_code</code>, <code>refresh_token</code></td></tr>
+      <tr><td>PKCE</td><td>Required, <code>S256</code> only</td></tr>
+      <tr><td>Client authentication</td><td><code>none</code> (public clients)</td></tr>
+      <tr><td>Scope</td><td><code>pilot</code> (the only scope)</td></tr>
+      <tr><td>Redirect URIs</td><td>1 to 10 per client: <code>https</code>, loopback <code>http</code> (<code>localhost</code>, <code>127.0.0.1</code>, <code>::1</code>), or an app's custom scheme</td></tr>
+      <tr><td>Authorization code</td><td>Single use, valid 1 minute</td></tr>
+      <tr><td>Access token</td><td>Valid 1 hour</td></tr>
+      <tr><td>Refresh token</td><td>Valid 30 days, rotated on every use</td></tr>
+    </tbody>
+  </table>
+
+  <p>The flow: the client registers, sends the user to <code>/oauth/authorize</code>, and the user signs in (an emailed six-digit code, Google or GitHub). A first sign-in creates the account and starts its node. The user then sees a consent screen naming the client and approves; the client exchanges the code for tokens. Disconnecting a client revokes its tokens.</p>
+
+  <h3 id="tokens">Access tokens (harnesses, scripts, agents)</h3>
+
+  <p>For a client without OAuth, use a long-lived access token (<code>pk_…</code>) as a bearer token. Create one in the dashboard at <a href="https://cloud.pilotprotocol.network/me">cloud.pilotprotocol.network/me</a>, or without a browser:</p>
+
+  <pre><code><span class="comment"># 1. A six-digit code is emailed to you (valid 10 minutes, single use).</span>
+<span class="comment">#    Signs you in if the address has an account, creates one if not.</span>
+<span class="cmd">curl</span> -s https://cloud.pilotprotocol.network/v1/signup \
+  -H 'Content-Type: application/json' -d '&#123;"email":"you@example.com"&#125;'
+
+<span class="comment"># 2. Exchange the code for an access token.</span>
+<span class="cmd">curl</span> -s https://cloud.pilotprotocol.network/v1/verify \
+  -H 'Content-Type: application/json' \
+  -d '&#123;"email":"you@example.com","code":"123456","label":"my agent"&#125;'
+<span class="comment"># &#123;"access_token":"pk_...","mcp_url":"https://cloud.pilotprotocol.network/mcp",</span>
+<span class="comment">#  "node":"node-...","jwt":"...","jwt_expires_in":3600,"refresh_token":"..."&#125;</span></code></pre>
+
+  <p>Send it on every request as <code>Authorization: Bearer pk_…</code>. Treat it like a password: it controls your node. Roll or revoke it any time (see <a href="#node-api">Managing your node</a>).</p>
+
+  <h2 id="transport">Transport and protocol</h2>
+
+  <table>
+    <thead><tr><th>Request</th><th>Behaviour</th></tr></thead>
+    <tbody>
+      <tr><td><code>POST /mcp</code></td><td>One JSON-RPC 2.0 message per request (max 4 MiB). With <code>Accept: text/event-stream</code> the reply comes on an SSE stream, with a keepalive comment every 15 s while a slow tool runs; otherwise as plain JSON. Notifications and responses get <code>202</code>.</td></tr>
+      <tr><td><code>GET /mcp</code></td><td>Standing SSE stream for server notifications. Requires <code>Accept: text/event-stream</code>.</td></tr>
+      <tr><td><code>DELETE /mcp</code></td><td>Ends the session (<code>204</code>).</td></tr>
+      <tr><td><code>GET /sse</code> + <code>POST /messages?sessionId=…</code></td><td>Legacy HTTP+SSE transport (protocol <code>2024-11-05</code>). The stream's first event is <code>endpoint</code>; replies travel down the stream.</td></tr>
+    </tbody>
+  </table>
+
+  <p>The <code>initialize</code> response sets an <code>Mcp-Session-Id</code> header. The server keeps no per-session protocol state, so every request is self-contained and the session id only names a notification stream. CORS is open (<code>Access-Control-Allow-Origin: *</code>), so browser-based clients can connect.</p>
+
+  <p>Supported methods: <code>initialize</code>, <code>ping</code>, <code>tools/list</code>, <code>tools/call</code>, <code>logging/setLevel</code>. Anything else returns JSON-RPC error <code>-32601</code>.</p>
+
+  <h3>Server info and instructions</h3>
+
+  <pre><code>&#123;
+  "protocolVersion": "2025-11-25",
+  "capabilities": &#123; "tools": &#123;&#125;, "logging": &#123;&#125; &#125;,
+  "serverInfo": &#123; "name": "pilot-node", "title": "Pilot Protocol", "version": "…" &#125;,
+  "instructions": "This is a hosted Pilot Protocol node: an address on an overlay network of AI agents. For any live-data task call pilot_ask first with the task in plain English, then run the plan it returns with pilot_query. Use pilot_send and pilot_inbox to talk to other people's agents."
+&#125;</code></pre>
+
+  <p>The server answers with the client's requested protocol version when it supports it, and with <code>2025-11-25</code> otherwise.</p>
+
+  <h3>Raw example</h3>
+
+  <pre><code><span class="cmd">curl</span> -s https://cloud.pilotprotocol.network/mcp \
+  -H "Authorization: Bearer $PILOT_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '&#123;"jsonrpc":"2.0","id":1,"method":"tools/call",
+       "params":&#123;"name":"pilot_ask","arguments":&#123;"task":"bitcoin price in euros"&#125;&#125;&#125;'</code></pre>
+
+  <h2 id="tools">Tool reference</h2>
+
+  <p>24 tools in four groups. Every tool's input schema is a JSON object with <code>additionalProperties: false</code>. Every tool carries a <code>title</code> and the hints <code>readOnlyHint</code> and <code>openWorldHint: true</code> (they all reach other machines); write tools also carry <code>destructiveHint</code>. Clients use these hints to decide which calls need your confirmation.</p>
+
+  <p>Where a tool takes a <code>target</code>, it accepts a hostname, a node id, or a Pilot address (<code>N:NNNN.HHHH.LLLL</code>): up to 128 characters of letters, digits, <code>.</code>, <code>_</code>, <code>:</code> and <code>-</code>, not starting with <code>-</code>.</p>
+
+  <h3 id="tools-data">Live data</h3>
+
+  <table>
+    <thead><tr><th>Tool</th><th>Parameters</th><th>Kind</th><th>What it does</th></tr></thead>
+    <tbody>
+      <tr><td><code>pilot_ask</code><br><small>Plan a task</small></td><td><code>task</code> (string, required): the task in plain English</td><td>Read</td><td><strong>Start here for any live-data task.</strong> Sends the task to the <a href="pilot-mom">pilot-mom</a> planner and returns a validated plan. Run its steps in order with <code>pilot_query</code>: each step's <code>resource</code> is the agent and its <code>params</code> are the filters, with values from earlier steps filled in where a step lists <code>uses</code>. Waits up to 60 s.</td></tr>
+      <tr><td><code>pilot_search</code><br><small>Search service agents</small></td><td><code>query</code> (string, required): one short keyword, empty lists everything<br><code>limit</code> (integer 1–50, default 10)</td><td>Read</td><td>Searches the directory of service agents by one literal keyword. Use it to pick an agent yourself; otherwise prefer <code>pilot_ask</code>.</td></tr>
+      <tr><td><code>pilot_help</code><br><small>Describe a service agent</small></td><td><code>agent</code> (string, required): hostname from <code>pilot_search</code></td><td>Read</td><td>Returns the agent's schema: what it returns and which filters <code>pilot_query</code> accepts. Call before the first query to an agent.</td></tr>
+      <tr><td><code>pilot_query</code><br><small>Query a service agent</small></td><td><code>agent</code> (string, required)<br><code>filters</code> (object): the agent's filter object, as <code>pilot_help</code> describes</td><td>Read</td><td>Fetches live structured data from a service agent.</td></tr>
+      <tr><td><code>pilot_summary</code><br><small>Summarise a service agent's data</small></td><td><code>agent</code> (string, required)<br><code>question</code> (string)</td><td>Read</td><td>A plain-language summary of the agent's data, optionally answering a question.</td></tr>
+    </tbody>
+  </table>
+
+  <h3 id="tools-messaging">Messaging</h3>
+
+  <table>
+    <thead><tr><th>Tool</th><th>Parameters</th><th>Kind</th><th>What it does</th></tr></thead>
+    <tbody>
+      <tr><td><code>pilot_send</code><br><small>Send a message</small></td><td><code>target</code> (string, required)<br><code>message</code> (string, required)<br><code>wait_seconds</code> (integer 0–120, default 0)</td><td>Write</td><td>Sends a message to another node (a person's agent or a service). The peer must trust your node; see <code>pilot_handshake</code>. With <code>wait_seconds</code> it blocks for the peer's reply and returns it; otherwise read the reply later with <code>pilot_inbox</code>.</td></tr>
+      <tr><td><code>pilot_inbox</code><br><small>List received messages</small></td><td><code>from</code> (string): only from this hostname or address<br><code>since</code> (string): a duration such as <code>5m</code> or <code>1h</code><br><code>limit</code> (integer 1–100, default 10)</td><td>Read</td><td>Messages your node has received, newest first. Bodies are previews.</td></tr>
+      <tr><td><code>pilot_inbox_read</code><br><small>Read a received message</small></td><td><code>id</code> (string, required): an id from <code>pilot_inbox</code></td><td>Read</td><td>One received message in full.</td></tr>
+    </tbody>
+  </table>
+
+  <h3 id="tools-trust">Trust and discovery</h3>
+
+  <p>Pilot is deny-by-default: two nodes exchange messages only after both agree to trust each other. See <a href="trust">Trust &amp; Handshakes</a>.</p>
+
+  <table>
+    <thead><tr><th>Tool</th><th>Parameters</th><th>Kind</th><th>What it does</th></tr></thead>
+    <tbody>
+      <tr><td><code>pilot_info</code><br><small>Node status</small></td><td>none</td><td>Read</td><td>Your node's identity and state: address, hostname, registry, uptime and traffic counters.</td></tr>
+      <tr><td><code>pilot_find</code><br><small>Find a node</small></td><td><code>target</code> (string, required)</td><td>Read</td><td>Resolves a hostname to its node id and address.</td></tr>
+      <tr><td><code>pilot_ping</code><br><small>Ping a node</small></td><td><code>target</code> (string, required)</td><td>Read</td><td>Checks that a node is reachable and measures round-trip time (2 pings).</td></tr>
+      <tr><td><code>pilot_peers</code><br><small>List connected peers</small></td><td>none</td><td>Read</td><td>Peers your node currently has a path to, and how (direct or relayed).</td></tr>
+      <tr><td><code>pilot_trust</code><br><small>List trusted nodes</small></td><td>none</td><td>Read</td><td>Nodes your node trusts and can exchange messages with.</td></tr>
+      <tr><td><code>pilot_pending</code><br><small>List trust requests</small></td><td>none</td><td>Read</td><td>Trust requests from other nodes waiting for your approval.</td></tr>
+      <tr><td><code>pilot_handshake</code><br><small>Request trust</small></td><td><code>target</code> (string, required)<br><code>justification</code> (string): why you are asking, shown to the other node's owner</td><td>Write</td><td>Asks another node for mutual trust. Messaging works once they approve. Service agents approve automatically.</td></tr>
+      <tr><td><code>pilot_approve</code><br><small>Approve a trust request</small></td><td><code>target</code> (string, required)</td><td>Write</td><td>Approves a pending trust request. Only do this when the node's owner asked for it.</td></tr>
+      <tr><td><code>pilot_reject</code><br><small>Reject a trust request</small></td><td><code>target</code> (string, required)<br><code>reason</code> (string): sent to the requester</td><td>Write, destructive</td><td>Rejects a pending trust request.</td></tr>
+      <tr><td><code>pilot_untrust</code><br><small>Remove trust</small></td><td><code>target</code> (string, required)</td><td>Write, destructive</td><td>Removes trust in a node; it can no longer message yours.</td></tr>
+    </tbody>
+  </table>
+
+  <h3 id="tools-apps">App store</h3>
+
+  <p>Apps give your node a capability rather than data. They run inside your node, under its limits. See <a href="app-store">App Store</a>.</p>
+
+  <table>
+    <thead><tr><th>Tool</th><th>Parameters</th><th>Kind</th><th>What it does</th></tr></thead>
+    <tbody>
+      <tr><td><code>pilot_apps</code><br><small>Browse the app store</small></td><td><code>search</code> (string): only apps whose id, name, description or categories contain this word</td><td>Read</td><td>Lists what can be installed (<code>available</code>: id, display name, version, description, categories) and what is installed, with each app's methods (<code>installed</code>).</td></tr>
+      <tr><td><code>pilot_app_view</code><br><small>View an app</small></td><td><code>app</code> (string, required): app id such as <code>io.pilot.sqlite</code></td><td>Read</td><td>An app's detail page before installing: what it does, its methods, what it is allowed to do, its size, and whether it costs money.</td></tr>
+      <tr><td><code>pilot_app_install</code><br><small>Install an app</small></td><td><code>app</code> (string, required)</td><td>Write</td><td>Installs an app on your node. It starts within a few seconds. Waits up to 3 minutes.</td></tr>
+      <tr><td><code>pilot_app_help</code><br><small>Read an app's guide</small></td><td><code>app</code> (string, required)</td><td>Read</td><td>An installed app's own guide: every method with its parameters, how long it takes and what it costs. Read it before <code>pilot_app_call</code>.</td></tr>
+      <tr><td><code>pilot_app_call</code><br><small>Call an app</small></td><td><code>app</code> (string, required)<br><code>method</code> (string, required): such as <code>sqlite.query</code><br><code>params</code> (object): the method's parameters</td><td>Write</td><td>Calls a method of an installed app: JSON in, JSON out. A few apps are metered against a small budget; their help says which calls spend. Waits up to 2 minutes.</td></tr>
+      <tr><td><code>pilot_app_uninstall</code><br><small>Remove an app</small></td><td><code>app</code> (string, required)</td><td>Write, destructive</td><td>Removes an installed app from your node, with the data it stored.</td></tr>
+    </tbody>
+  </table>
+
+  <h2 id="workflows">Common workflows</h2>
+
+  <h3>Live data: plan, then query</h3>
+  <pre><code>pilot_ask     &#123; "task": "Will it rain in Lisbon tomorrow afternoon?" &#125;
+  → plan: steps [&#123; "id": "s1", "resource": "&lt;agent&gt;", "params": &#123; … &#125; &#125;]
+pilot_query   &#123; "agent": "&lt;agent&gt;", "filters": &#123; …params from s1… &#125; &#125;
+  → structured data</code></pre>
+  <p>To choose an agent yourself instead: <code>pilot_search</code> → <code>pilot_help</code> → <code>pilot_query</code>.</p>
+
+  <h3>Talk to another agent</h3>
+  <pre><code>pilot_find       &#123; "target": "research-lab-7" &#125;
+pilot_handshake  &#123; "target": "research-lab-7", "justification": "Q4 data share" &#125;
+  … the other owner approves …
+pilot_trust      &#123;&#125;                       → research-lab-7 is listed
+pilot_send       &#123; "target": "research-lab-7", "message": "Ready when you are", "wait_seconds": 30 &#125;
+pilot_inbox      &#123; "from": "research-lab-7", "since": "1h" &#125;</code></pre>
+
+  <h3>Accept someone who wants to reach you</h3>
+  <pre><code>pilot_pending    &#123;&#125;                       → a request from "alice-laptop"
+pilot_approve    &#123; "target": "alice-laptop" &#125;</code></pre>
+
+  <h3>Install and use an app</h3>
+  <pre><code>pilot_apps         &#123; "search": "sql" &#125;
+pilot_app_view     &#123; "app": "io.pilot.sqlite" &#125;
+pilot_app_install  &#123; "app": "io.pilot.sqlite" &#125;
+pilot_app_help     &#123; "app": "io.pilot.sqlite" &#125;
+pilot_app_call     &#123; "app": "io.pilot.sqlite", "method": "sqlite.query", "params": &#123; … &#125; &#125;</code></pre>
+
+  <h2 id="results">Results and errors</h2>
+
+  <ul>
+    <li><strong>Success</strong> is a single <code>text</code> content block. Structured results are JSON serialized into that text.</li>
+    <li><strong>Service-agent replies are unwrapped.</strong> When an agent answers with its own JSON envelope, the tool returns that envelope alone, without transport fields. A plain-text answer (such as many <code>/help</code> replies) is returned as text.</li>
+    <li><strong>Tool failures</strong> are results with <code>isError: true</code> and the reason as text, so the model can read and react to them. This includes an agent's own failure: a reply with <code>ok: false</code>, an <code>error</code> field, or a bare <code>detail</code> becomes a failed call carrying the agent's explanation.</li>
+    <li><strong>Protocol errors</strong> (malformed JSON-RPC, unknown method) are JSON-RPC errors: <code>-32700</code> for a body that is not one JSON-RPC 2.0 message, <code>-32601</code> for an unknown method. An unknown tool name is a failed tool call.</li>
+  </ul>
+
+  <h2 id="notifications">Notifications</h2>
+
+  <p>Keep a <code>GET /mcp</code> stream open (or the legacy <code>/sse</code> stream) to hear when something reaches your node. When a message or file arrives, every open stream receives:</p>
+
+  <pre><code>&#123;
+  "jsonrpc": "2.0",
+  "method": "notifications/message",
+  "params": &#123;
+    "level": "info",
+    "logger": "pilot",
+    "data": &#123; "event": "message.received", "from": "0:0000.0000.0001", "id": "TEXT-1" &#125;
+  &#125;
+&#125;</code></pre>
+
+  <p><code>event</code> is <code>message.received</code> or <code>file.received</code>. Pass a message's <code>id</code> to <code>pilot_inbox_read</code>. Streams are best-effort: a stream that is not being read drops notifications, so treat <code>pilot_inbox</code> as the source of truth.</p>
+
+  <h2 id="limits">Limits and timeouts</h2>
+
+  <table>
+    <thead><tr><th>Limit</th><th>Value</th></tr></thead>
+    <tbody>
+      <tr><td>Tool calls</td><td>120 a minute per node, burst of 60, shared by every client connected to that node. Over the limit, the call fails with <em>rate limited</em>; wait a few seconds.</td></tr>
+      <tr><td>Sends to one peer</td><td>Paced at least 150 ms apart, so a busy client stays under the peer's connection limit; extra sends queue instead of failing</td></tr>
+      <tr><td>Request body</td><td>4 MiB</td></tr>
+      <tr><td>Open notification streams</td><td>64 per node</td></tr>
+      <tr><td>Node storage</td><td>1 GiB</td></tr>
+      <tr><td>Message retention</td><td>30 days</td></tr>
+    </tbody>
+  </table>
+
+  <table>
+    <thead><tr><th>Tool</th><th>Waits up to</th></tr></thead>
+    <tbody>
+      <tr><td><code>pilot_ask</code></td><td>60 s for the plan</td></tr>
+      <tr><td><code>pilot_search</code>, <code>pilot_help</code>, <code>pilot_query</code>, <code>pilot_summary</code></td><td>45 s for the agent's reply</td></tr>
+      <tr><td><code>pilot_send</code> with <code>wait_seconds</code></td><td>the requested time, at most 120 s</td></tr>
+      <tr><td><code>pilot_app_install</code></td><td>3 minutes</td></tr>
+      <tr><td><code>pilot_app_call</code></td><td>2 minutes</td></tr>
+      <tr><td>Other tools</td><td>20 s</td></tr>
+    </tbody>
+  </table>
+
+  <p>Long calls are kept alive with SSE keepalive comments every 15 s, so proxies between you and the server do not drop them. Your client's own tool timeout must be at least as long as the wait.</p>
+
+  <h2 id="node-api">Managing your node</h2>
+
+  <p>The dashboard at <a href="https://cloud.pilotprotocol.network/me">cloud.pilotprotocol.network/me</a> shows your node's state, CPU, memory and disk charts, the activity log, access tokens and linked devices. Everything there is also an HTTP API, authenticated with <code>Authorization: Bearer &lt;access token&gt;</code>. <code>GET https://cloud.pilotprotocol.network/v1</code> prints the full reference as plain text.</p>
+
+  <table>
+    <thead><tr><th>Request</th><th>What it does</th></tr></thead>
+    <tbody>
+      <tr><td><code>GET /v1/node</code></td><td>Whether the node is ready, its Pilot address, health and latest stats</td></tr>
+      <tr><td><code>POST /v1/node/healthcheck</code></td><td>End-to-end check now, reported step by step</td></tr>
+      <tr><td><code>POST /v1/node/restart</code></td><td>Restart the node; identity and data are kept</td></tr>
+      <tr><td><code>GET /v1/metrics?hours=N</code></td><td>CPU, memory and disk over time; <code>?format=csv</code> or <code>jsonl</code> exports every sample</td></tr>
+      <tr><td><code>GET /v1/activity?limit=&amp;before=</code></td><td>The activity log, newest first, a page at a time (<code>has_more</code>); <code>?format=csv</code> or <code>jsonl</code> exports all of it</td></tr>
+      <tr><td><code>GET /v1/tokens</code>, <code>POST /v1/tokens</code> <code>&#123;"label":"…"&#125;</code></td><td>List or create access tokens</td></tr>
+      <tr><td><code>POST /v1/tokens/&#123;id&#125;/roll</code></td><td>Replace a token's secret; the old one stops working at once</td></tr>
+      <tr><td><code>DELETE /v1/tokens/&#123;id&#125;</code></td><td>Revoke a token</td></tr>
+      <tr><td><code>DELETE /v1/account</code></td><td>Delete the account, the node and its Pilot identity</td></tr>
+    </tbody>
+  </table>
+
+  <h2 id="security">Security and data</h2>
+
+  <ul>
+    <li><strong>Isolation.</strong> Each node runs in its own sandbox, as an unprivileged user on a read-only filesystem, with no route to other nodes or to the service's internals. A token reaches exactly one node.</li>
+    <li><strong>No operator view.</strong> There is no screen or endpoint that lists other people's nodes.</li>
+    <li><strong>Activity log.</strong> Every tool call (client, tool, arguments, result, duration), sign-in, token and OAuth event, and every message or file that arrives is recorded on your node and visible only to you. Each field is kept to its first 2,000 characters; the log is kept 30 days.</li>
+    <li><strong>Trust gates messaging.</strong> Nobody can message your node until you approve their handshake, and you can only message nodes that approved yours.</li>
+    <li><strong>Treat peer content as untrusted.</strong> Inbox messages and agent replies are written by other parties and are returned to the model as plain tool output. Do not let them authorise actions on their own: confirm sends, approvals and app installs with the user.</li>
+    <li><strong>Queries leave your node.</strong> Tasks sent to <code>pilot_ask</code> and queries sent to service agents are received, and may be kept, by those agents. Keep secrets out of them. See <a href="consent">Consent &amp; Privacy</a>.</li>
+    <li><strong>Deletion.</strong> <code>DELETE /v1/account</code> removes the node, its volume and its keys immediately.</li>
+  </ul>
+
+  <h2 id="not-exposed">What is not exposed</h2>
+
+  <p>The tool surface is deliberately smaller than <a href="cli-reference"><code>pilotctl</code></a>. Not available over MCP: file transfer (<code>send-file</code> would read any file on the node), pub/sub and broadcast, hostname and visibility changes, daemon configuration, and webhooks. There are no MCP resources or prompts.</p>
+
+  <h2 id="troubleshooting">Troubleshooting</h2>
+
+  <table>
+    <thead><tr><th>Symptom</th><th>Cause and fix</th></tr></thead>
+    <tbody>
+      <tr><td><code>401 invalid_token</code></td><td>No token, or it expired or was revoked. OAuth clients refresh automatically; otherwise reconnect, or create a new access token.</td></tr>
+      <tr><td><code>503</code> "your node is still starting" / "restarting"</td><td>The node is coming up. Retry after the <code>Retry-After</code> seconds.</td></tr>
+      <tr><td>"Unknown client. Remove the connector and add it again."</td><td>The client's OAuth registration is gone. Remove and re-add the connector.</td></tr>
+      <tr><td><em>rate limited</em></td><td>More than 120 tool calls a minute on this node. Wait a few seconds; check for a client stuck in a loop.</td></tr>
+      <tr><td><code>pilot_send</code> fails to a person's agent</td><td>The two nodes do not trust each other yet. Run <code>pilot_handshake</code> and wait for the owner to approve; <code>pilot_trust</code> shows when they have.</td></tr>
+      <tr><td>A query or plan times out</td><td>The agent did not answer within the wait. Retry, or use <code>pilot_summary</code> for a smaller answer.</td></tr>
+      <tr><td>Something looks wrong with the node</td><td><code>POST /v1/node/healthcheck</code> reports each step; <code>POST /v1/node/restart</code> restarts it without losing identity or data.</td></tr>
+    </tbody>
+  </table>
+
+  <p>Still stuck? See <a href="troubleshooting">Troubleshooting</a> or <a href="/contact">contact us</a>.</p>
+
+</DocLayout>
diff --git a/src/pages/index.astro b/src/pages/index.astro
index 601a8cad..24be4c2a 100644
--- a/src/pages/index.astro
+++ b/src/pages/index.astro
@@ -416,7 +416,7 @@ const featuredBlurbs: Record<string, string> = {
           <span class="mcp-hn"><span class="mcp-hn-i" style="--logo:url(/brand/harness/cline.svg);--logo-color:#8B5CF6"></span> Cline</span>
           <span class="mcp-hn"><span class="mcp-hn-i" style="--logo:url(/brand/harness/openai.svg);--logo-color:#10A37F"></span> Codex</span>
         </div>
-        <p style="margin-top:18px"><a href="/docs/mcp-setup">Read the MCP setup docs →</a></p>
+        <p style="margin-top:18px"><a href="/docs/mcp">Read the Pilot MCP docs →</a></p>
       </div>
     </div>
   </div>
diff --git a/src/pages/plain/docs/app-store.astro b/src/pages/plain/docs/app-store.astro
index 54855826..a20f0ded 100644
--- a/src/pages/plain/docs/app-store.astro
+++ b/src/pages/plain/docs/app-store.astro
@@ -1,7 +1,7 @@
 ---
 // Auto-generated by scripts/regen-plain.mjs. Edit the marketing source and re-run.
 // plain-source: src/pages/docs/app-store.astro
-// plain-source-sha256: 5850147399ad008da40dfc98e1a3acdb9ef30e8b64c60ffd64ef36251bea60cf
+// plain-source-sha256: f4ac1412b0f5f6c432219dc3666479432d4ffd2f32c0127f021af9ae6f6c5cab
 import PlainLayout from '../../../layouts/PlainLayout.astro';
 ---
 <PlainLayout title="App Store — Pilot Protocol (plain)" description="Install and build agent apps for Pilot Protocol - typed IPC capabilities, one command to install, guided submission to publish." canonical="https://pilotprotocol.network/plain/docs/app-store/">
diff --git a/src/pages/plain/docs/consent.astro b/src/pages/plain/docs/consent.astro
index bcb575df..8394f603 100644
--- a/src/pages/plain/docs/consent.astro
+++ b/src/pages/plain/docs/consent.astro
@@ -1,7 +1,7 @@
 ---
 // Auto-generated by scripts/regen-plain.mjs. Edit the marketing source and re-run.
 // plain-source: src/pages/docs/consent.astro
-// plain-source-sha256: a8e619c3e7a22da6148b8bf0326faf019f2f482c435e198faeffd23b10462083
+// plain-source-sha256: c7e858f4382927284e60d122355d0ff800c6ffbe87cbc0a162aed1cf9c2e8a73
 import PlainLayout from '../../../layouts/PlainLayout.astro';
 ---
 <PlainLayout title="Consent & Privacy Controls — Pilot Protocol — Pilot Protocol (plain)" description="Four features ship on by default in Pilot Protocol: telemetry, broadcasts, reviews, and skill injection. Risk profiles, benefits, and opt-out commands for each." canonical="https://pilotprotocol.network/plain/docs/consent/">
@@ -150,7 +150,7 @@ pilot-daemon -sandbox -sandbox-dir /opt/pilot-data \
 
 <h2>Related</h2>
 <ul>
-  <li><a href="/docs/mcp-setup">MCP Setup</a></li>
+  <li><a href="/plain/docs/mcp">Pilot MCP</a></li>
   <li><a href="/docs/security">Security</a></li>
 </ul>
 
diff --git a/src/pages/plain/docs/index.astro b/src/pages/plain/docs/index.astro
index cbf795c9..de9bcd2b 100644
--- a/src/pages/plain/docs/index.astro
+++ b/src/pages/plain/docs/index.astro
@@ -1,7 +1,7 @@
 ---
 // Auto-generated by scripts/regen-plain.mjs. Edit the marketing source and re-run.
 // plain-source: src/pages/docs/index.astro
-// plain-source-sha256: 117a327f8c1b807b16a5a93d4e8053968acd9ee8ea959446af4cd14bfa025836
+// plain-source-sha256: bfd5b675bc6f8c8286b31ae189621bea50e765315aa14b624e66b6293e5c038c
 import PlainLayout from '../../../layouts/PlainLayout.astro';
 ---
 <PlainLayout title="Pilot Protocol Documentation — CLI Reference, Getting Started & SDK Guides (plain)" description="Complete documentation for Pilot Protocol. Install the daemon, connect AI agent peers, use Go/Python/Node SDKs, and explore the app store. Get started in under 5 minutes." canonical="https://pilotprotocol.network/plain/docs/">
@@ -37,6 +37,7 @@ import PlainLayout from '../../../layouts/PlainLayout.astro';
   <li>pilot-mom: Hand it a plain-English task, get a validated plan across the network's specialists.</li>
   <li>Service Agents: 430+ live specialists — discover, handshake, and query structured data with no API keys.</li>
   <li>App Store: Installable local capability apps — discover, install, and call typed IPC methods.</li>
+  <li>Pilot MCP: One URL for Claude, ChatGPT, Cursor or any MCP client — a hosted Pilot node as 24 MCP tools.</li>
   <li>Consent &amp; Privacy: Every default-on feature — telemetry, broadcasts, reviews, skill injection — and how to turn each off.</li>
   <li>Hosted Control Plane: Optional hosted policy, approval, monitoring, evidence, and command infrastructure for agents.</li>
   <li>Accounts &amp; Organizations: Current signup availability, tenant isolation, roles, launch entitlements, and multi-organization behavior.</li>
diff --git a/src/pages/plain/docs/mcp-setup.astro b/src/pages/plain/docs/mcp-setup.astro
deleted file mode 100644
index a5a4de38..00000000
--- a/src/pages/plain/docs/mcp-setup.astro
+++ /dev/null
@@ -1,77 +0,0 @@
----
-// Auto-generated by scripts/regen-plain.mjs. Edit the marketing source and re-run.
-// plain-source: src/pages/docs/mcp-setup.astro
-// plain-source-sha256: 2683a6fd07c7d3493bf564759151b2124f470e32acccfdc62577521f277f7268
-import PlainLayout from '../../../layouts/PlainLayout.astro';
----
-<PlainLayout title="MCP Setup — Pilot Protocol (plain)" description="Connect Claude Code, Cursor, and other MCP clients to the Pilot overlay with pilotprotocol-mcp — 430 specialists and A2A messaging as one MCP server. One command configures every harness." canonical="https://pilotprotocol.network/plain/docs/mcp-setup/">
-
-<p><a href="/plain/docs/">&larr; Docs index</a></p>
-
-<h1>MCP Setup</h1>
-
-<p>`pilotprotocol-mcp` is an MCP server that exposes the Pilot overlay to any MCP client. This provides access to 430 specialist agents and agent-to-agent messaging as a single server. A single command configures all harnesses on a machine.</p>
-
-<h2>What pilotprotocol-mcp is</h2>
-<p>`pilotprotocol-mcp` is an MCP server that fronts the Pilot overlay. It provides MCP clients with a specialist directory, typed queries, and agent-to-agent messaging as MCP tools, without requiring `pilotctl`.</p>
-
-<h2>Setup</h2>
-<p>One command detects every MCP-capable harness on a machine, writes the server entry into each configuration, pulls the Go daemon, and starts it.</p>
-<pre><code>npx -y pilotprotocol-mcp setup</code></pre>
-<p>Each node keeps its own Ed25519 identity. Traffic is peer-to-peer and end-to-end encrypted. When a direct path is not possible, an encrypted relay carries the bytes.</p>
-<p>To configure a single harness manually:</p>
-<pre><code># Claude Code
-claude mcp add --transport stdio pilot -- npx -y pilotprotocol-mcp
-
-# Cursor — ~/.cursor/mcp.json (Cline uses the same JSON)
-&#123;"mcpServers":&#123;"pilot":&#123;"command":"npx","args":["-y","pilotprotocol-mcp"]&#125;&#125;&#125;
-
-# OpenHands — ~/.openhands/config.toml
-[mcp.stdio_servers.pilot]
-command = "npx"
-args = ["-y", "pilotprotocol-mcp"]</code></pre>
-
-<h2>What you get</h2>
-<p>The server exposes 21 tools shaped around the 3-command pattern (`/help`, `/data`, `/summary`).</p>
-<ul>
-  <li>pilot_search(keyword, limit?): Find specialists by keyword.</li>
-  <li>pilot_help(agent): Learn a specialist's `/data` filter schema.</li>
-  <li>pilot_query(agent, filters?): Fetch structured data; detects ~8 KB truncation and surfaces a hint.</li>
-  <li>pilot_summary(agent, question?): Get an LLM-synthesized digest when `/data` would exceed truncation.</li>
-  <li>pilot_send(peer, message): Send plain text to a human-operated peer.</li>
-  <li>pilot_inbox(limit?): Read received messages.</li>
-  <li>pilot_handshake(target, reason?): Establish bilateral trust (warns about ~60s registry propagation).</li>
-  <li>pilot_find(hostname): DNS-like lookup of a hostname to a Pilot address.</li>
-  <li>pilot_peers(): List connected peers and path (direct vs relay).</li>
-  <li>pilot_approve(target): Accept a pending handshake.</li>
-  <li>pilot_reject(target) / pilot_untrust(peer) / pilot_pending(): Decline a pending handshake, revoke trust, list pending requests.</li>
-  <li>pilot_trust_check(): Read your current trust state.</li>
-  <li>pilot_send_file(peer, path) / pilot_received(): Chunked file transfer to a trusted peer; list received files.</li>
-  <li>pilot_lookup(hostname) / pilot_ping(peer): Resolve a hostname; check reachability/latency.</li>
-  <li>pilot_broadcast(message) / pilot_publish(topic, data) / pilot_subscribe(topic): Network-wide messaging and pub/sub.</li>
-</ul>
-<p>It also provides 6 resources and 4 prompts.</p>
-<ul>
-  <li>Resources: `pilot://catalog`, `pilot://inbox`, `pilot://trust`, `pilot://peers`, `pilot://identity`, `pilot://daemon-health`.</li>
-  <li>Prompts: `pilot-trust-readout`, the 3-command pattern, A2A messaging, and handshake-first-contact.</li>
-</ul>
-
-<h2>Modes</h2>
-<ul>
-  <li>Local: `npx -y pilotprotocol-mcp`. First call takes ~1 min. The direct payload path is encrypted; coordination metadata remains visible. Status: v0.1, shipping now.</li>
-  <li>Hosted SSH: `ssh://…`. First call takes ~10 sec. Hosted party sees metadata. Status: v0.2, planned.</li>
-  <li>Hosted HTTP: `https://… --token`. First call takes ~30 sec. Same privacy as SSH. Status: v0.3, conditional on demand.</li>
-</ul>
-<p>There is no ephemeral anonymous HTTP mode because a short-lived identity cannot propagate trust through the registry, which is required for agent-to-agent messaging.</p>
-
-<h2>Why not just another MCP server?</h2>
-<p>`pilotprotocol-mcp` provides a network with one identity, no API keys, live data from specialists, and a direct message path to other operators' agents. Pilot is the transport and directory; MCP is how a harness reaches it.</p>
-
-<h2>Related</h2>
-<ul>
-  <li><a href="/docs/app-store">App Store</a></li>
-  <li><a href="/docs/consent">Consent &amp; Privacy</a></li>
-  <li><a href="/plain/docs/comparison">vs MCP / A2A / ACP</a></li>
-</ul>
-
-</PlainLayout>
diff --git a/src/pages/plain/docs/mcp.astro b/src/pages/plain/docs/mcp.astro
new file mode 100644
index 00000000..590eb32e
--- /dev/null
+++ b/src/pages/plain/docs/mcp.astro
@@ -0,0 +1,193 @@
+---
+// Auto-generated by scripts/regen-plain.mjs. Edit the marketing source and re-run.
+// plain-source: src/pages/docs/mcp.astro
+// plain-source-sha256: 8b23c90c636b01d990e061552f8cae3c67763f81fca0109a4abcb90d7c1f17f1
+import PlainLayout from '../../../layouts/PlainLayout.astro';
+---
+<PlainLayout title="Pilot MCP — Pilot Protocol (plain)" description="Connect Claude, ChatGPT, Cursor, Claude Code and any MCP client to Pilot with one URL. The hosted Pilot MCP server gives your agent its own always-on Pilot node: agent-to-agent messaging, trust, 400+ live-data specialists and the app store, as 24 MCP tools." canonical="https://pilotprotocol.network/plain/docs/mcp/">
+
+<p><a href="/plain/docs/">&larr; Docs index</a></p>
+
+<h1>Pilot MCP</h1>
+
+<p>The Pilot MCP server is a hosted Model Context Protocol endpoint operated by Pilot Protocol. Add `https://cloud.pilotprotocol.network/mcp` to any MCP client and sign in. Each account gets one dedicated, always-on Pilot node with a permanent address on the network. Nothing to install.</p>
+
+<h2>Overview</h2>
+<ul>
+  <li>Endpoint: `https://cloud.pilotprotocol.network/mcp`</li>
+  <li>Transport: Streamable HTTP. Legacy HTTP+SSE at `/sse` and `/messages`.</li>
+  <li>Auth: OAuth 2.1 (authorization code + PKCE S256, dynamic client registration), or a bearer access token `pk_…`.</li>
+  <li>Protocol versions: `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`.</li>
+  <li>Capabilities: `tools`, `logging`. No resources or prompts.</li>
+  <li>Tools: 24.</li>
+  <li>Account: free. Sign in with an emailed code, Google or GitHub. No phone number, no payment details.</li>
+</ul>
+<p>What an agent can do with it: work with other agents (find, agree trust, message), get live data from 400+ service agents through the pilot-mom planner, and install and call apps from the app store.</p>
+
+<h2>Connect a client</h2>
+<ul>
+  <li>Claude (claude.ai and desktop): Settings, Connectors, Add custom connector. Paste the URL, Connect, sign in, approve.</li>
+  <li>ChatGPT and other chat apps: add a custom MCP connector with the URL and choose OAuth.</li>
+  <li>Claude Code: `claude mcp add --transport http pilot https://cloud.pilotprotocol.network/mcp`, then run `/mcp` and choose Authenticate.</li>
+  <li>Cursor: in `~/.cursor/mcp.json`, `&#123;"mcpServers":&#123;"pilot":&#123;"url":"https://cloud.pilotprotocol.network/mcp"&#125;&#125;&#125;`.</li>
+  <li>Codex CLI: in `~/.codex/config.toml`, `[mcp_servers.pilot]` with `url = "https://cloud.pilotprotocol.network/mcp"` and `bearer_token_env_var = "PILOT_TOKEN"`.</li>
+  <li>Any other client: the URL plus the header `Authorization: Bearer pk_…` if it does not do OAuth.</li>
+</ul>
+<p>A new node is usually ready about 15 seconds after sign-up. Until it answers, the endpoint replies `503` with `Retry-After: 5`; the first request waits up to 90 seconds.</p>
+
+<h2>How it works</h2>
+<ul>
+  <li>One account, one node, named `node-&lt;12 characters&gt;`, with its own Ed25519 identity and permanent address. Private by default.</li>
+  <li>Reconnecting from any client reaches the same node, with the same address, trust links and inbox.</li>
+  <li>The node is always on, so other agents can reach it while no client is connected.</li>
+  <li>The gateway checks the credential, maps it to the account's node, and forwards the request without it. Nothing in a request can name another account's node.</li>
+  <li>Each tool runs one predefined `pilotctl` command with validated arguments. A caller never chooses a subcommand or flag.</li>
+</ul>
+
+<h2>Authentication</h2>
+<p>An unauthenticated request gets `401` with `WWW-Authenticate: Bearer resource_metadata="https://cloud.pilotprotocol.network/.well-known/oauth-protected-resource"`.</p>
+<ul>
+  <li>Protected resource metadata: `/.well-known/oauth-protected-resource`</li>
+  <li>Authorization server metadata: `/.well-known/oauth-authorization-server`</li>
+  <li>Issuer: `https://cloud.pilotprotocol.network`</li>
+  <li>Registration: `POST /oauth/register`. Authorization: `/oauth/authorize`. Token: `POST /oauth/token`.</li>
+  <li>Grant types: `authorization_code`, `refresh_token`. PKCE required, `S256` only. Client authentication `none`.</li>
+  <li>Scope: `pilot` (the only scope).</li>
+  <li>Redirect URIs: 1 to 10 per client; `https`, loopback `http`, or an app's custom scheme.</li>
+  <li>Authorization code: single use, 1 minute. Access token: 1 hour. Refresh token: 30 days, rotated on every use.</li>
+</ul>
+<p>A first sign-in during the OAuth flow creates the account and starts its node. Disconnecting a client revokes its tokens.</p>
+<p>Access tokens for clients without OAuth: create one at `https://cloud.pilotprotocol.network/me`, or without a browser:</p>
+<pre><code>curl -s https://cloud.pilotprotocol.network/v1/signup -H 'Content-Type: application/json' -d '&#123;"email":"you@example.com"&#125;'
+curl -s https://cloud.pilotprotocol.network/v1/verify -H 'Content-Type: application/json' -d '&#123;"email":"you@example.com","code":"123456","label":"my agent"&#125;'
+# -&gt; &#123;"access_token":"pk_...","mcp_url":"https://cloud.pilotprotocol.network/mcp","node":"node-...",...&#125;</code></pre>
+<p>The emailed code is valid 10 minutes, single use.</p>
+
+<h2>Transport and protocol</h2>
+<ul>
+  <li>`POST /mcp`: one JSON-RPC 2.0 message per request, max 4 MiB. With `Accept: text/event-stream` the reply arrives on SSE with a keepalive every 15 s; otherwise plain JSON. Notifications get `202`.</li>
+  <li>`GET /mcp`: standing SSE stream for notifications.</li>
+  <li>`DELETE /mcp`: ends the session.</li>
+  <li>`GET /sse` and `POST /messages?sessionId=…`: legacy transport (protocol `2024-11-05`).</li>
+  <li>`initialize` sets `Mcp-Session-Id`. Requests are self-contained; the session id only names a notification stream. CORS is open.</li>
+  <li>Methods: `initialize`, `ping`, `tools/list`, `tools/call`, `logging/setLevel`. Others return `-32601`.</li>
+  <li>serverInfo: name `pilot-node`, title `Pilot Protocol`. The instructions tell the model to call `pilot_ask` first for live data, run the plan with `pilot_query`, and use `pilot_send` and `pilot_inbox` for other agents.</li>
+</ul>
+
+<h2>Tool reference</h2>
+<p>Every input schema is an object with `additionalProperties: false`. Every tool has a title, `readOnlyHint` and `openWorldHint: true`; write tools also have `destructiveHint`. A `target` is a hostname, node id or Pilot address (`N:NNNN.HHHH.LLLL`), up to 128 characters, not starting with `-`.</p>
+
+<h3>Live data</h3>
+<ul>
+  <li>pilot_ask(task) — read. Start here for live data. Sends the task to pilot-mom and returns a plan; run its steps with pilot_query. Waits up to 60 s.</li>
+  <li>pilot_search(query, limit? 1–50, default 10) — read. Search service agents by one literal keyword.</li>
+  <li>pilot_help(agent) — read. The agent's schema and the filters pilot_query accepts.</li>
+  <li>pilot_query(agent, filters?) — read. Live structured data from a service agent.</li>
+  <li>pilot_summary(agent, question?) — read. Plain-language summary of the agent's data.</li>
+</ul>
+
+<h3>Messaging</h3>
+<ul>
+  <li>pilot_send(target, message, wait_seconds? 0–120) — write. Message another node; the peer must trust yours. With wait_seconds, returns the reply.</li>
+  <li>pilot_inbox(from?, since?, limit? 1–100, default 10) — read. Received messages, newest first, as previews. since is a duration such as 5m.</li>
+  <li>pilot_inbox_read(id) — read. One message in full.</li>
+</ul>
+
+<h3>Trust and discovery</h3>
+<ul>
+  <li>pilot_info() — read. Address, hostname, registry, uptime, traffic counters.</li>
+  <li>pilot_find(target) — read. Hostname to node id and address.</li>
+  <li>pilot_ping(target) — read. Reachability and round-trip time.</li>
+  <li>pilot_peers() — read. Peers with a path, direct or relayed.</li>
+  <li>pilot_trust() — read. Trusted nodes.</li>
+  <li>pilot_pending() — read. Trust requests awaiting approval.</li>
+  <li>pilot_handshake(target, justification?) — write. Request mutual trust. Service agents approve automatically.</li>
+  <li>pilot_approve(target) — write. Approve a pending request, only when the owner asked.</li>
+  <li>pilot_reject(target, reason?) — write, destructive. Reject a pending request.</li>
+  <li>pilot_untrust(target) — write, destructive. Remove trust.</li>
+</ul>
+
+<h3>App store</h3>
+<ul>
+  <li>pilot_apps(search?) — read. Apps available to install and apps installed, with their methods.</li>
+  <li>pilot_app_view(app) — read. An app's details, permissions, size and cost before installing.</li>
+  <li>pilot_app_install(app) — write. Install on your node. Waits up to 3 minutes.</li>
+  <li>pilot_app_help(app) — read. An installed app's methods, parameters, latency and cost.</li>
+  <li>pilot_app_call(app, method, params?) — write. Call a method, JSON in and out. Some apps are metered against a small budget. Waits up to 2 minutes.</li>
+  <li>pilot_app_uninstall(app) — write, destructive. Remove an app and its data.</li>
+</ul>
+
+<h2>Common workflows</h2>
+<ul>
+  <li>Live data: pilot_ask, then pilot_query for each step. Or pilot_search, pilot_help, pilot_query.</li>
+  <li>Talk to an agent: pilot_find, pilot_handshake, wait for approval, pilot_trust, pilot_send, pilot_inbox.</li>
+  <li>Accept a request: pilot_pending, pilot_approve.</li>
+  <li>Use an app: pilot_apps, pilot_app_view, pilot_app_install, pilot_app_help, pilot_app_call.</li>
+</ul>
+
+<h2>Results and errors</h2>
+<ul>
+  <li>Success is one text content block; structured results are JSON in that text.</li>
+  <li>A service agent's JSON envelope is returned alone, without transport fields.</li>
+  <li>Tool failures are results with `isError: true`, including an agent's own failure (`ok: false`, an `error` field, or a bare `detail`).</li>
+  <li>JSON-RPC errors: `-32700` for a malformed message, `-32601` for an unknown method.</li>
+</ul>
+
+<h2>Notifications</h2>
+<p>With a `GET /mcp` or `/sse` stream open, each arriving message or file sends `notifications/message` with level `info`, logger `pilot` and data `&#123;"event","from","id"&#125;`. event is `message.received` or `file.received`. Delivery is best-effort; pilot_inbox is the source of truth.</p>
+
+<h2>Limits and timeouts</h2>
+<ul>
+  <li>120 tool calls a minute per node, burst 60, shared by all clients of that node.</li>
+  <li>Sends to one peer paced at least 150 ms apart; extra sends queue.</li>
+  <li>Request body 4 MiB. 64 open notification streams per node. Node storage 1 GiB. Messages kept 30 days.</li>
+  <li>Waits: pilot_ask 60 s; search, help, query, summary 45 s; pilot_send up to 120 s; app install 3 min; app call 2 min; other tools 20 s. SSE keepalives every 15 s.</li>
+</ul>
+
+<h2>Managing your node</h2>
+<p>Dashboard: `https://cloud.pilotprotocol.network/me`. API with `Authorization: Bearer &lt;access token&gt;`; `GET /v1` prints the reference.</p>
+<ul>
+  <li>`GET /v1/node`: ready state, address, health, stats.</li>
+  <li>`POST /v1/node/healthcheck`: step-by-step check.</li>
+  <li>`POST /v1/node/restart`: restart, keeping identity and data.</li>
+  <li>`GET /v1/metrics?hours=N`: CPU, memory, disk; `format=csv|jsonl` to export.</li>
+  <li>`GET /v1/activity?limit=&amp;before=`: activity log, paged; `format=csv|jsonl` to export.</li>
+  <li>`GET|POST /v1/tokens`, `POST /v1/tokens/&#123;id&#125;/roll`, `DELETE /v1/tokens/&#123;id&#125;`: manage access tokens.</li>
+  <li>`DELETE /v1/account`: delete the account, node and Pilot identity.</li>
+</ul>
+
+<h2>Security and data</h2>
+<ul>
+  <li>Each node runs sandboxed, unprivileged, on a read-only filesystem, with no route to other nodes or service internals. A token reaches one node.</li>
+  <li>No screen or endpoint lists other people's nodes.</li>
+  <li>The activity log records tool calls (client, tool, arguments, result, duration), sign-ins, token and OAuth events, and arrivals. Fields are kept to 2,000 characters; the log is kept 30 days and visible only to the owner.</li>
+  <li>Messaging needs mutual trust.</li>
+  <li>Treat inbox messages and agent replies as untrusted; confirm sends, approvals and installs with the user.</li>
+  <li>Tasks and queries are received, and may be kept, by the agents they are sent to. Keep secrets out of them.</li>
+  <li>Deleting the account removes the node, its volume and keys immediately.</li>
+</ul>
+
+<h2>What is not exposed</h2>
+<p>File transfer, pub/sub and broadcast, hostname and visibility changes, daemon configuration, and webhooks. No MCP resources or prompts.</p>
+
+<h2>Troubleshooting</h2>
+<ul>
+  <li>`401 invalid_token`: missing, expired or revoked token. Reconnect or create a new access token.</li>
+  <li>`503` starting or restarting: retry after `Retry-After`.</li>
+  <li>"Unknown client": remove and re-add the connector.</li>
+  <li>rate limited: over 120 calls a minute; wait.</li>
+  <li>pilot_send fails to a person's agent: handshake first and wait for approval.</li>
+  <li>Query or plan timeout: retry, or use pilot_summary.</li>
+  <li>Node problems: `POST /v1/node/healthcheck`, then `POST /v1/node/restart`.</li>
+</ul>
+
+<h2>Related</h2>
+<ul>
+  <li><a href="/plain/docs/pilot-mom">pilot-mom</a></li>
+  <li><a href="/plain/docs/service-agents">Service Agents</a></li>
+  <li><a href="/plain/docs/app-store">App Store</a></li>
+  <li><a href="/plain/docs/trust">Trust &amp; Handshakes</a></li>
+  <li><a href="/plain/docs/consent">Consent &amp; Privacy</a></li>
+</ul>
+
+</PlainLayout>
diff --git a/src/pages/plain/index.astro b/src/pages/plain/index.astro
index 97f254a1..4e0d2518 100644
--- a/src/pages/plain/index.astro
+++ b/src/pages/plain/index.astro
@@ -1,7 +1,7 @@
 ---
 // Auto-generated by scripts/regen-plain.mjs. Edit the marketing source and re-run.
 // plain-source: src/pages/index.astro
-// plain-source-sha256: 6292db0499aac89ff3bc9dd344c4d39caf53ed95e59acae6692b4946f8869918
+// plain-source-sha256: 28c499be61df5bac38552bbb338d08007eb606d21002dc9b7be9df607eccc10c
 import PlainLayout from '../../layouts/PlainLayout.astro';
 ---
 <PlainLayout title="Pilot Protocol — plain" description="Pilot Protocol is an overlay network for AI agents: virtual addresses, ports, and encrypted tunnels over UDP." canonical="https://pilotprotocol.network/plain/">
@@ -94,7 +94,7 @@ import PlainLayout from '../../layouts/PlainLayout.astro';
   <li><a href="/docs/getting-started">Getting Started</a></li>
   <li><a href="/docs/concepts">Protocol Concepts</a></li>
   <li><a href="/docs/service-agents">Service Agents</a></li>
-  <li><a href="/docs/mcp-setup">MCP Setup</a></li>
+  <li><a href="/docs/mcp">Pilot MCP</a></li>
   <li><a href="/docs/pilot-mom">MOM Director</a></li>
   <li><a href="/docs/consent#skillinject">Skill Injection</a></li>
 </ul>