From bcbc3503548c9fef5bac9963e034f77f1105facf Mon Sep 17 00:00:00 2001
From: Sameh Khamis <sameh@halfpixel.ai>
Date: Fri, 2 Oct 2026 18:23:56 -0700
Subject: [PATCH] docs: add a one-page MCP setup for Claude and Codex

Steps people and coding agents can follow to run the app, add the MCP
server to Claude Code, Claude Desktop, the Codex CLI and the Codex and
ChatGPT desktop apps, and check it works, linked from the README and the
tools guide.
---
 README.md         |  2 ++
 docs/MCP_SETUP.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++
 docs/TOOLS.md     |  2 ++
 3 files changed, 76 insertions(+)
 create mode 100644 docs/MCP_SETUP.md

diff --git a/README.md b/README.md
index f6a3ae886..13ff96215 100644
--- a/README.md
+++ b/README.md
@@ -279,6 +279,8 @@ _Ask for radio near anywhere and the globe starts broadcasting — every station
 
 ---
 
+**💬 Or ask from Claude and Codex.** God's Eye View is also an MCP server: ask Claude Desktop, Codex or ChatGPT desktop to show a place, and the live globe opens right in the conversation. Setup takes a minute — see [docs/MCP_SETUP.md](docs/MCP_SETUP.md).
+
 ## 🛰️ What's on the Globe
 
 Nineteen layers and map sources. **Seventeen have a keyless path.** Some offer additional capabilities with a provider key. (🟢 no key · 🟡 free key · 🔴 metered.)
diff --git a/docs/MCP_SETUP.md b/docs/MCP_SETUP.md
new file mode 100644
index 000000000..bd5e52c26
--- /dev/null
+++ b/docs/MCP_SETUP.md
@@ -0,0 +1,72 @@
+# MCP setup
+
+Use God's Eye View from Claude and Codex: tools, links, and the live globe
+inside the conversation. Agents: follow these steps in order and check each
+one before going on.
+
+## 1. Run the app
+
+```sh
+npm install
+npm run build:panel   # the in-conversation globe; rerun after app changes
+npm run dev           # http://localhost:5173, keep it running
+```
+
+The MCP server reads from this app. Check: `curl -sI http://localhost:5173/panel/`
+answers `200`.
+
+## 2. Add the server to a client
+
+The server is `server/mcp/stdio.js` in this checkout. Use absolute paths
+(clients do not load your shell profile), with each argument as its own entry.
+
+| Client | How |
+| --- | --- |
+| Claude Code | `claude mcp add gods-eye-view -- node /abs/path/gods-eye-view/server/mcp/stdio.js --api-base http://localhost:5173` |
+| Codex CLI | `codex mcp add gods-eye-view -- node /abs/path/gods-eye-view/server/mcp/stdio.js --api-base http://localhost:5173` |
+| Codex and ChatGPT desktop | Same `~/.codex/config.toml` as the CLI (block below), or Settings → MCP servers → Add server (STDIO). |
+| Claude Desktop | Settings → Developer → Edit Config, then add the JSON below. |
+
+```toml
+[mcp_servers.gods-eye-view]
+command = "node"
+args = ["/abs/path/gods-eye-view/server/mcp/stdio.js", "--api-base", "http://localhost:5173"]
+```
+
+```json
+{
+  "mcpServers": {
+    "gods-eye-view": {
+      "command": "node",
+      "args": ["/abs/path/gods-eye-view/server/mcp/stdio.js", "--api-base", "http://localhost:5173"]
+    }
+  }
+}
+```
+
+**Windows with the checkout in WSL:** use `"command": "wsl.exe"` and put
+`"-e"` and the absolute Linux path to `node` first in `args`, for example
+`["-e", "/home/you/.local/share/mise/installs/node/24/bin/node", "/home/you/gods-eye-view/server/mcp/stdio.js", "--api-base", "http://localhost:5173"]`.
+
+## 3. Restart and try it
+
+Fully quit the client (on Windows, from the tray icon) and reopen it, then
+start a new chat; clients keep the server they started with. Ask: *"Show San
+Diego in God's Eye View with military flights on."*
+
+- Claude Desktop (a chat, not the Code tab), Codex and ChatGPT desktop show
+  the live globe; the first load takes 10–20 seconds.
+- Claude Code and the Codex CLI answer with data and a link.
+
+## Troubleshooting
+
+- **The server does not appear:** run the command from step 2 in a terminal;
+  it should print `God's Eye View MCP server reading http://localhost:5173`
+  and wait. A path or `args` mistake fails here.
+- **The panel says it could not load:** `npm run build:panel` was not run, or
+  the dev server is down.
+- **Logs:** the server writes each call, and why one failed, to stderr. Claude
+  Desktop keeps it in its logs folder as `mcp-server-gods-eye-view.log`; in
+  Codex, right-click the panel → DevTools for the panel's console.
+
+See [tools and the MCP server](TOOLS.md) for what the tools do.
diff --git a/docs/TOOLS.md b/docs/TOOLS.md
index c216d365f..4ed69db69 100644
--- a/docs/TOOLS.md
+++ b/docs/TOOLS.md
@@ -4,6 +4,8 @@ Tools answer questions from God's Eye View data for language-model clients.
 They are defined once and exposed through adapters: the Model Context Protocol
 (MCP) and function calling, which voice uses.
 
+To use them from Claude or Codex, see [MCP setup](MCP_SETUP.md).
+
 ## Layers
 
 | Owner                | Responsibility                                                                                    |