136 lines
7.6 KiB
Markdown
136 lines
7.6 KiB
Markdown
# 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.
|
||
|
||
### VS Code template
|
||
|
||
Use this shape in `mcp.json`; adapt the secret-input syntax to the installed VS Code build. Never replace placeholders with token values in a tracked file.
|
||
|
||
```json
|
||
{
|
||
"servers": {
|
||
"hoppe-brain": { "type": "http", "url": "https://hoppe.mywire.org/brain/mcp", "headers": { "Authorization": "Bearer ${input:hoppe-brain-token}" } },
|
||
"hoppe-codebox": { "type": "http", "url": "https://hoppe.mywire.org/codebox/mcp", "headers": { "Authorization": "Bearer ${input:hoppe-codebox-token}" } },
|
||
"hoppe-estate": { "type": "http", "url": "https://hoppe.home/api/portal/estate/mcp", "headers": { "Authorization": "Bearer ${input:hoppe-estate-token}" } },
|
||
"hoppe-h365": { "type": "http", "url": "https://hoppe.mywire.org/365/mcp", "headers": { "Authorization": "Bearer ${input:hoppe-h365-token}" } },
|
||
"hoppe-ideahub": { "type": "http", "url": "https://hoppe.mywire.org/ideahub/mcp", "headers": { "Authorization": "Bearer ${input:hoppe-ideahub-token}" } },
|
||
"hoppe-obs": { "type": "http", "url": "https://hoppe.mywire.org/obs/mcp", "headers": { "Authorization": "Bearer ${input:hoppe-obs-token}" } },
|
||
"hoppe-ops": { "type": "http", "url": "https://hoppe-apps.hoppe.home/ops/mcp", "headers": { "Authorization": "Bearer ${input:hoppe-ops-token}" } }
|
||
}
|
||
}
|
||
```
|
||
|
||
If the client does not support `${input:...}`, use its secret store or environment substitution. Do not commit a rendered configuration containing credentials.
|
||
|
||
## 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
|
||
|
||
Codex and Antigravity must preserve the same seven names and URLs. Use each client's supported secret-reference syntax; VS Code's `${input:...}` syntax is not necessarily valid in TOML or another JSON schema.
|
||
|
||
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.
|
||
|
||
## Safe validation procedure
|
||
|
||
1. Confirm the machine can resolve and reach the relevant hostname. Estate and Ops require the Hoppe.home network path or VPN.
|
||
2. Validate the client configuration syntax before restarting it.
|
||
3. Restart or reload the client and run its MCP server-list/status command.
|
||
4. For each server, confirm an `initialize` handshake succeeds with HTTP 200.
|
||
5. Redact `Authorization` headers, token values, cookies, and secret-bearing request bodies from diagnostics.
|
||
|
||
Do not test a bearer-protected endpoint in a browser address bar or with a URL query parameter. A 401 can demonstrate reachability, but it does not validate a credential.
|
||
|
||
## Troubleshooting
|
||
|
||
| Symptom | Likely cause | Action |
|
||
|---|---|---|
|
||
| 401 Unauthorized | Missing, expired, or wrong token | Retrieve the matching Vault entry and re-enter it through the client's secret mechanism. |
|
||
| 404 Not Found | Wrong route or path | Compare the endpoint character-for-character with the matrix; do not swap online and local routes. |
|
||
| DNS, timeout, or connection failure | Network/VPN, proxy, or TLS issue | Check the required network path, proxy/VPN, and system time. |
|
||
| `initialize` timeout | Transport/configuration mismatch | Confirm the client supports remote HTTP MCP and is not configured for local stdio. |
|
||
| Claude requests OAuth registration | Connector policy requires OAuth | Mark it pending administrator setup; do not put a bearer token in OAuth fields. |
|
||
|
||
Escalate with client name, server name, timestamp, HTTP status, and redacted diagnostics. Do not send token values or unredacted logs.
|
||
|
||
## 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.
|
