diff --git a/MCP-CLIENT-ONBOARDING.md b/MCP-CLIENT-ONBOARDING.md
new file mode 100644
index 0000000..7b94c71
--- /dev/null
+++ b/MCP-CLIENT-ONBOARDING.md
@@ -0,0 +1,91 @@
+# Hoppe.home MCP client onboarding
+
+This runbook keeps Codebox Go, VS Code, Codex Desktop, Antigravity, and Claude aligned on the same Hoppe.home MCP topology.
+
+## Server matrix
+
+Use the online routes for the five remotely reachable services:
+
+| Server | Online endpoint |
+|---|---|
+| Brain | `https://hoppe.mywire.org/brain/mcp` |
+| Codebox | `https://hoppe.mywire.org/codebox/mcp` |
+| H365 | `https://hoppe.mywire.org/365/mcp` |
+| IdeaHub | `https://hoppe.mywire.org/ideahub/mcp` |
+| OBS | `https://hoppe.mywire.org/obs/mcp` |
+
+Estate and Ops are local Hoppe.home routes in this profile:
+
+| Server | Local Hoppe.home endpoint |
+|---|---|
+| Estate | `https://hoppe.home/api/portal/estate/mcp` |
+| Ops | `https://hoppe-apps.hoppe.home/ops/mcp` |
+
+Do not substitute a bearer token into a URL. Send it only as an `Authorization: Bearer ...` header.
+
+## Secrets and Vault
+
+Bearer tokens are restricted credentials. They must be stored in the approved Hoppe.home Vault under the Donny VS Code/Copilot client profile, with separate entries for:
+
+`HOPPE_BRAIN_MCP_TOKEN`, `HOPPE_CODEBOX_MCP_TOKEN`, `HOPPE_ESTATE_MCP_TOKEN`, `HOPPE_H365_MCP_TOKEN`, `HOPPE_IDEAHUB_MCP_TOKEN`, `HOPPE_OBS_MCP_TOKEN`, and `HOPPE_OPS_MCP_TOKEN`.
+
+Never commit tokens, paste them into this repository, place them in screenshots, or print them in chat/logs. A new machine must retrieve them from Vault or use the approved secret-injection process; this guide does not prove Vault contents.
+
+## New-machine Codebox Go setup
+
+1. Clone the workspace/bootstrap repository using the current Codebox Go Git URL.
+2. Run `workspace\bootstrap.ps1` and sign in with the user’s Codebox Go account.
+3. Open the generated `Codebox Go.code-workspace` in VS Code.
+4. Run the sync script when required:
+
+   ```powershell
+   powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\workspace\sync-codebox.ps1 -Root .
+   ```
+
+5. Confirm that each repository is a separate clone and that local changes are not overwritten.
+
+## VS Code configuration
+
+VS Code reads the user MCP file at:
+
+`%APPDATA%\Code\User\mcp.json`
+
+The workspace copy is:
+
+`.vscode\mcp.json`
+
+Register all seven server names exactly as `hoppe-brain`, `hoppe-codebox`, `hoppe-estate`, `hoppe-h365`, `hoppe-ideahub`, `hoppe-obs`, and `hoppe-ops`. Keep credentials as environment or input placeholders, never literal values. Reload the VS Code window, then run **MCP: List Servers** and inspect each server’s connection status.
+
+Expected verification is an MCP `initialize` response with HTTP 200. A 401 means the credential is missing/invalid; a 404 means the route is wrong for that network profile.
+
+## Codex Desktop
+
+Codex uses:
+
+`%USERPROFILE%\.codex\config.toml`
+
+Add the same seven server names and endpoint matrix. Keep credentials in the client’s supported secret mechanism. Restart Codex after changing the file and confirm all seven entries appear enabled in MCP settings.
+
+## Gemini Antigravity
+
+Antigravity uses:
+
+`%USERPROFILE%\.gemini\config\mcp_config.json`
+
+Use the same seven names, URLs, and bearer-header secret references. Validate the JSON, restart Antigravity, and confirm there are no `initialize: Unauthorized` errors.
+
+## Claude Desktop / Claude Connectors
+
+Claude’s custom connector UI accepts one remote MCP URL at a time. Add the seven endpoints from the server matrix with matching display names. Claude may require OAuth discovery or an OAuth client ID; a bearer token is not an OAuth client ID. Do not enter Hoppe bearer tokens into the OAuth client ID or secret fields. If the server requires an OAuth registration that Hoppe.home does not provide, record the connector as pending administrator setup rather than weakening authentication.
+
+## Alignment checklist
+
+- [ ] All seven server names match across clients.
+- [ ] Five services use `hoppe.mywire.org` online routes.
+- [ ] Estate and Ops use the local Hoppe.home routes for this profile.
+- [ ] Tokens are present in the approved Vault and absent from Git, screenshots, and chat.
+- [ ] VS Code, Codex, and Antigravity have been restarted after configuration changes.
+- [ ] Each client has been checked for MCP initialization success.
+- [ ] Claude connectors have completed OAuth discovery/authorization, or are explicitly marked pending.
+
+Last verified for this profile: Brain, Codebox, H365, IdeaHub, and OBS returned HTTP 200 on the online routes; Estate and Ops returned HTTP 200 on the local Hoppe.home routes. Verification was performed without exposing credential values.
diff --git a/README.md b/README.md
index 86a0da6..ccc83f4 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,6 @@
 # codebox-go-guide
 
-How to connect VS Code to Codebox Go. Public guide for family and external collaborators.
\ No newline at end of file
+How to connect VS Code to Codebox Go. Public guide for family and external collaborators.
+
+For the complete Hoppe.home MCP, VS Code, Codex Desktop, Antigravity, Claude
+connector, and Vault runbook, see [`MCP-CLIENT-ONBOARDING.md`](MCP-CLIENT-ONBOARDING.md).