Docs: add MCP client onboarding guide #1
@@ -58,6 +58,26 @@ Register all seven server names exactly as `hoppe-brain`, `hoppe-codebox`, `hopp
|
||||
|
||||
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:
|
||||
@@ -68,6 +88,8 @@ Add the same seven server names and endpoint matrix. Keep credentials in the cli
|
||||
|
||||
## 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`
|
||||
@@ -78,6 +100,28 @@ Use the same seven names, URLs, and bearer-header secret references. Validate th
|
||||
|
||||
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.
|
||||
|
||||
@@ -0,0 +1,68 @@
|
||||
# MCP tool access report
|
||||
|
||||
**Checked:** 2026-09-19, Europe/Berlin
|
||||
|
||||
## Executive summary
|
||||
|
||||
The current session exposes 72 callable MCP tools across four namespaces:
|
||||
|
||||
| Namespace | Exposed tools | Live read-only check |
|
||||
|---|---:|---|
|
||||
| `hoppe_brain` | 38 | PASS: `brainStatus` |
|
||||
| `hoppe_codebox` | 17 | PASS: identity and repository listing |
|
||||
| `codex_apps` | 14 | PASS: document-session discovery; no sessions connected |
|
||||
| `node_repl` | 3 | Exposed; not executed for this audit |
|
||||
|
||||
H365 is reported as connection-ready, but its `H365MCP-Donny` tool namespace is not loaded in this particular session. Estate, Ops, IdeaHub, and OBS remain unexposed and unverified here.
|
||||
|
||||
## Available tools
|
||||
|
||||
### Hoppe Brain — 38
|
||||
|
||||
`approveSupersession`, `brainExport`, `brainSchemaVersion`, `brainStatus`, `brainVerifyExport`, `createRelationship`, `explainSystem`, `getActiveAlerts`, `getCapabilityReliability`, `getGraph`, `getIdentity`, `getMonitoringSchema`, `getProject`, `getProtocol`, `getScopedGraph`, `getServerHealth`, `learnFromErrors`, `listCapabilities`, `listDocuments`, `listKnowledge`, `listRisks`, `queryMonitoring`, `readNote`, `recordCorrection`, `recordError`, `recordToolExecution`, `reviewBrain`, `reviewDrift`, `reviewSupersessions`, `routeIntent`, `searchBrain`, `setNodeStatus`, `submitDreaming`, `supersedeNode`, `whatChanged`, `whyBroke`, `writeMemory`, `writeNote`.
|
||||
|
||||
Read-only status access succeeded. The `getIdentity` check returned an MCP internal error (`-32603: 'name'`), so Brain identity was not independently verified.
|
||||
|
||||
### Hoppe Codebox — 17
|
||||
|
||||
`codeboxAddComment`, `codeboxCommitFile`, `codeboxCreateBranch`, `codeboxCreateIssue`, `codeboxCreatePullRequest`, `codeboxDeleteFile`, `codeboxGetFile`, `codeboxGetIssue`, `codeboxGetPullRequest`, `codeboxListBranches`, `codeboxListCommits`, `codeboxListFiles`, `codeboxListIssues`, `codeboxListPullRequests`, `codeboxListRepos`, `codeboxUpdateIssue`, `codeboxWhoAmI`.
|
||||
|
||||
`codeboxWhoAmI` succeeded and identified the active account as Donny (ID 12, Hoppe.home organization; not a site admin). Repository listing also succeeded. No write or delete operation was performed for this audit.
|
||||
|
||||
### Codex Apps — 14
|
||||
|
||||
Document control: `codex_document_control_execute_document_command`, `codex_document_control_get_document_tool_schemas`, `codex_document_control_list_document_sessions`.
|
||||
|
||||
Plugin management: `plugin_management_get_app_permissions`, `plugin_management_get_plugin_dependencies`, `plugin_management_search_plugins`, `plugin_management_suggest_plugins`, `plugin_management_uninstall_app`, `plugin_management_update_app_permissions`.
|
||||
|
||||
Safety settings: `safety_settings_get_family_info`, `safety_settings_get_parental_controls`, `safety_settings_get_trusted_contact`, `safety_settings_prepare_parental_control_update`, `safety_settings_update_parental_control`.
|
||||
|
||||
Document-session discovery succeeded, but returned no connected document sessions. No plugin, permission, or safety-setting changes were performed.
|
||||
|
||||
### Node REPL — 3
|
||||
|
||||
`js`, `js_add_node_module_dir`, and `js_reset` are exposed. They were not executed for this audit.
|
||||
|
||||
## Missing or unverified server coverage
|
||||
|
||||
The onboarding topology names seven Hoppe.home services:
|
||||
|
||||
| Service | Expected endpoint | Dedicated tool namespace in this session | Status |
|
||||
|---|---|---|---|
|
||||
| Brain | `https://hoppe.mywire.org/brain/mcp` | `hoppe_brain` | Available; read-only status passed |
|
||||
| Codebox | `https://hoppe.mywire.org/codebox/mcp` | `hoppe_codebox` | Available; identity and listing passed |
|
||||
| H365 | `https://hoppe.mywire.org/365/mcp` | `H365MCP-Donny` (not loaded in this session) | Connection reported active; tools unavailable in this session |
|
||||
| IdeaHub | `https://hoppe.mywire.org/ideahub/mcp` | None | Missing/unverified |
|
||||
| OBS | `https://hoppe.mywire.org/obs/mcp` | None | Missing/unverified |
|
||||
| Estate | `https://hoppe.home/api/portal/estate/mcp` | None | Missing/unverified |
|
||||
| Ops | `https://hoppe-apps.hoppe.home/ops/mcp` | None | Missing/unverified |
|
||||
|
||||
## Resources and limitations
|
||||
|
||||
The MCP resource inventory exposed two `codex_apps` resources for plugin management and no resource templates. Tool exposure is not proof that every backend is authorized or healthy. Write-capable tools were intentionally not invoked merely to test them.
|
||||
|
||||
## Recommended next steps
|
||||
|
||||
1. Install/connect the missing H365, IdeaHub, OBS, Estate, and Ops MCP integrations or expose their namespaces in the client configuration.
|
||||
2. Add a read-only health or identity operation for each service so availability can be tested without changing state.
|
||||
3. Re-run this audit after configuration changes and record HTTP/MCP initialization results separately from tool exposure.
|
||||
Reference in New Issue
Block a user
