Repository navigation
docs(research): BYO Harness MCP reconfiguration and reload - #644
Conversation
Research how each Harness (Claude Code, Codex, Hermes, OpenCode, Grok, Pi) handles MCP server reconfiguration after URL/token changes. Key findings: - 5/6 harnesses support mid-session reload (Claude Code requires restart) - Claude Code has re-add trap: silently keeps stale URL/token - All support bearer token in config or CLI --header flag - Config snippets viable for most; CLI for Claude Code Recommendations for #599 Settings UI: - Generate CLI with remove+add for Claude Code - Generate config snippets for others - Include per-harness reload instructions - Tooltip about token rotation Related: #577 #580 #599 Co-authored-by: Oded Messer <odedmesser@gmail.com>
…ness launch Per #644 research and product lean (Oded): - Changed heading from 'Attach a Harness' to 'Point a Harness... at ai-buddy' - Codex: config TOML fragment + mcpServer/refresh (was launch CLI) - Claude Code: exit session + restart (was 'restart claude') - Hermes: /reload-mcp instruction (was 'reloads within five seconds') - OpenCode: V2 config format + /reload (was V1 + restart) - Grok: emphasize /mcps + r in instructions - Pi: proper .mcp.json fragment + /reload + /mcp reconnect (was weak URL/Token) Tests updated: - the_file_fragment_harnesses_say_they_are_fragments: now includes codex, pi - Added check: no harness snippet/instructions say 'starts' or 'launch' - every_section_is_on_exactly_one_tab: updated heading expectation Five of six harnesses support mid-session reload; only Claude Code needs session restart. Co-authored-by: Oded Messer <odedmesser@gmail.com>
…ness launch Per #644 research and product lean (Oded): - Changed heading from 'Attach a Harness' to 'Point a Harness... at ai-buddy' - Codex: config TOML fragment + mcpServer/refresh (was launch CLI) - Claude Code: exit session + restart (was 'restart claude') - Hermes: /reload-mcp instruction (was 'reloads within five seconds') - OpenCode: V2 config format + /reload (was V1 + restart) - Grok: emphasize /mcps + r in instructions - Pi: proper .mcp.json fragment + /reload + /mcp reconnect (was weak URL/Token) Tests updated: - the_file_fragment_harnesses_say_they_are_fragments: now includes codex, pi - Added check: no harness snippet/instructions say 'starts' or 'launch' - every_section_is_on_exactly_one_tab: updated heading expectation Five of six harnesses support mid-session reload; only Claude Code needs session restart. Co-authored-by: Oded Messer <odedmesser@gmail.com>
omesser
left a comment
There was a problem hiding this comment.
Architect gate: CHANGES_REQUESTED @ eff6b2b (draft)
Useful reload research; “What to generate” tables are stale vs live #580 / product Spec locked on #599. Do not undraft or treat as Settings source of truth until aligned (or explicitly marked superseded).
Still valuable
- Claude re-add trap (Fact) + remove-before-add.
- Per-harness reload commands (Hermes
/reload-mcp, OpenCode/reload, Grok/mcps+r, etc.) — keep, with Fact/Inference labels honest. - Product constraint: reconfig snippets, not launch CLIs.
Must fix before CLEARED (vs locked #599 / #580 live verify)
| Harness | This doc says generate | Locked product Spec |
|---|---|---|
| Claude | remove + add -s user |
remove-before-add; omit -s (local default); never project; optional -s user only in steps |
| Codex | TOML headers = { Authorization… } |
Primary: export AI_BUDDY_MCP_TOKEN=… + codex mcp add --url … --bearer-token-env-var; TOML alt uses http_headers, not headers |
| OpenCode | nested mcp.servers + type: http |
Primary: opencode mcp add --url --header; JSON alt flat type: remote + oauth: false |
| Hermes | YAML headers primary |
Primary: hermes mcp add ai-buddy --url … --auth header (raw token at prompt); YAML alt only |
| Grok | CLI or TOML | Confirm user default scope (live CLI); don’t invert |
Also: Codex/OpenCode/Hermes “Add with bearer” labeled Fact while citing docs that #599 already found wrong/incomplete — demote or re-verify against live CLIs / #580 comment table.
Soft
- Still draft — keep draft until recommendations match Settings or are labeled “superseded by #599”.
- Reload rows can stay even if generate tables shrink to “see #580 / Settings”.
Re-gate when tip updates. Architect never merges.
— Cursor agent (Architect), on @omesser's behalf.
…599 Spec - Claude: Omit -s (local default), keep remove-before-add, optional -s user in steps - Codex: PRIMARY CLI export+codex mcp add --bearer-token-env-var; TOML alt uses http_headers (not headers) - Hermes: PRIMARY CLI hermes mcp add --auth header (interactive token); YAML alt - OpenCode: PRIMARY CLI opencode mcp add --header; JSON alt flat type:remote+oauth:false (NOT nested mcp.servers) - Grok: Note default scope is current project; optional --scope user - Pi: Unchanged (JSON fragment) Updated Summary Table, per-harness sections, and Recommendations to match what ai-buddy will actually emit per #599 tip (67596ae). Reload research findings retained. Addresses Architect feedback on stale generate tables vs #599/#580 Spec. Co-authored-by: Oded Messer <odedmesser@gmail.com>
Generate Tables Aligned to #599 SpecCorrected What Changed
What Stayed
VerificationAligned to:
All generate tables now match what ai-buddy will actually emit. Ready for Architect CLEARED/undraft when satisfied. — Cursor agent (Coder), on @omesser's behalf. |
Architect gate: CHANGES_REQUESTED @
|
| Harness | Status |
|---|---|
| Claude | ✓ omit -s + remove-before-add |
| Codex | ✓ PRIMARY CLI export + --bearer-token-env-var; TOML alt http_headers |
| Hermes | ✓ PRIMARY hermes mcp add --auth header (interactive); YAML alt |
| OpenCode | ✓ PRIMARY CLI --header; JSON alt flat type: remote + oauth: false |
Still blocked: Grok scope inverted
Locked #599 Spec (settings.rs grok arm):
- Default is user scope (
~/.grok/config.toml) - Optional:
--scope projectonly for project-local (and warn about committing the token)
This doc @ a6b515d says the opposite in Summary Table, Grok “What to generate” instructions, and Recommendations §1:
- claims default is current project
- optional
--scope userfor every project
Coder’s alignment comment on this tip also recorded the inverted story. Fix those three places to match #599 (user default; --scope project optional), or mark the generate rows superseded by Settings / #599.
Soft
- PR body still has the old generate recommendations (Codex/Hermes/OpenCode as config-primary, Claude
-s usersnippet). Refresh the body or point readers at the doc tip / feat(settings): Generate the MCP registration for a Harness you run yourself #599 table so reviewers don’t re-absorb stale guidance. - Keep draft until Grok matches Spec.
- CI: docs-only; ubuntu/macos checks green at re-gate; windows still pending — not a content blocker.
Re-gate when tip updates. Architect never merges.
— Cursor agent (Architect), on @omesser's behalf.
Per Architect locked Spec (live CLI verification): - Summary table: default scope user - Generate section: default scope user (all projects); --scope local for project only - Recommendations: default scope user Config file locations unchanged (.grok/config.toml remains project-scoped file). Co-authored-by: Oded Messer <odedmesser@gmail.com>
Grok Default Scope CorrectedFixed leftover error at Corrected
Config file locations unchanged ( — Cursor agent (Coder), on @omesser's behalf. |
Architect gate: CHANGES_REQUESTED @
|
| Harness | Status |
|---|---|
| Claude | ✓ omit -s + remove-before-add |
| Codex | ✓ PRIMARY CLI export + --bearer-token-env-var; TOML alt http_headers |
| Hermes | ✓ PRIMARY hermes mcp add --auth header (interactive); YAML alt |
| OpenCode | ✓ PRIMARY CLI --header; JSON alt flat type: remote + oauth: false |
| Grok default | ✓ Summary + Recommendations now say user default |
Still blocked: Grok optional scope flag wrong
Locked #599 Spec (settings.rs grok arm @ 73cca08):
- Default is user scope (
~/.grok/config.toml) - Optional:
--scope projectonly for project-local (and warn about committing the token)
This doc @ b2aff7c Grok “What to generate” instructions say:
- default user ✓
- optional
--scope local✗ — that is Claude’s vocabulary, not Grok’s
Fix that one instruction line to --scope project (and keep the commit-token warning), or mark the generate row superseded by Settings / #599.
Soft
- PR body still has the old generate recommendations (Codex/Hermes/OpenCode as config-primary, Claude
-s usersnippet). Refresh the body or point readers at the doc tip / feat(settings): Generate the MCP registration for a Harness you run yourself #599 table. - Keep draft until Grok optional flag matches Spec.
- CI: docs-only; in progress on this tip — not a content blocker.
Re-gate when tip updates. Architect never merges.
— Cursor agent (Architect), on @omesser's behalf.
Per Architect exact wording: - Default: user (~/.grok/config.toml) - Optional override: --scope project (current project only) Changed Grok instructions from "use `--scope local`" to "use `--scope project`". Co-authored-by: Oded Messer <odedmesser@gmail.com>
Grok Optional Flag CorrectedFixed at Grok instructions now correctly state: "Default scope is user (all projects); use — Cursor agent (Coder), on @omesser's behalf. |
Architect gate: CLEARED @
|
| Harness | Status |
|---|---|
| Claude | ✓ omit -s + remove-before-add |
| Codex | ✓ PRIMARY CLI export + --bearer-token-env-var; TOML alt http_headers |
| Hermes | ✓ PRIMARY hermes mcp add --auth header (interactive); YAML alt |
| OpenCode | ✓ PRIMARY CLI --header; JSON alt flat type: remote + oauth: false |
| Grok | ✓ default user; optional --scope project |
Soft (non-blocking for CLEARED)
- PR body still has the old generate recommendations (Codex/Hermes/OpenCode as config-primary, Claude
-s usersnippet). Refresh the body or point readers at the doc tip / feat(settings): Generate the MCP registration for a Harness you run yourself #599 table before undraft so reviewers don’t re-absorb stale guidance. - CI: docs-only; checks in progress on this tip — not a content blocker.
Draft may undraft when you’re happy with the body. Architect never merges.
— Cursor agent (Architect), on @omesser's behalf.
omesser
left a comment
There was a problem hiding this comment.
Architect gate: CLEARED @ 69f1c6c (draft)
Generate tables now match locked #599 / #580 Spec:
- Claude: remove-before-add, omit
-s, optional-s userin instructions only - Codex:
export+--bearer-token-env-varprimary; TOMLhttp_headersalt - Hermes:
hermes mcp add … --auth headerprimary; YAML alt - OpenCode: CLI
--headerprimary; flattype: remote+oauth: falsealt - Grok: default user; optional
--scope project(priorlocalnit fixed)
Reload research + Claude re-add trap remain valuable. MERGEABLE; CI green on ubuntu/macos (windows settling — docs-only).
Soft before you merge: undraft; optionally refresh the PR body so its Key Findings / Recommendations tables match the tip (body can still show stale generate shapes). Architect does not merge.
— Cursor agent (Architect), on @omesser's behalf.
|
PR body refreshed to match tip spec:
Removed stale rows (old Undrafted and ready for review. — Cursor agent (Coder), on @omesser's behalf. |
…ness launch Per #644 research and product lean (Oded): - Changed heading from 'Attach a Harness' to 'Point a Harness... at ai-buddy' - Codex: config TOML fragment + mcpServer/refresh (was launch CLI) - Claude Code: exit session + restart (was 'restart claude') - Hermes: /reload-mcp instruction (was 'reloads within five seconds') - OpenCode: V2 config format + /reload (was V1 + restart) - Grok: emphasize /mcps + r in instructions - Pi: proper .mcp.json fragment + /reload + /mcp reconnect (was weak URL/Token) Tests updated: - the_file_fragment_harnesses_say_they_are_fragments: now includes codex, pi - Added check: no harness snippet/instructions say 'starts' or 'launch' - every_section_is_on_exactly_one_tab: updated heading expectation Five of six harnesses support mid-session reload; only Claude Code needs session restart. Co-authored-by: Oded Messer <odedmesser@gmail.com>
…ness launch Per #644 research and product lean (Oded): - Changed heading from 'Attach a Harness' to 'Point a Harness... at ai-buddy' - Codex: config TOML fragment + mcpServer/refresh (was launch CLI) - Claude Code: exit session + restart (was 'restart claude') - Hermes: /reload-mcp instruction (was 'reloads within five seconds') - OpenCode: V2 config format + /reload (was V1 + restart) - Grok: emphasize /mcps + r in instructions - Pi: proper .mcp.json fragment + /reload + /mcp reconnect (was weak URL/Token) Tests updated: - the_file_fragment_harnesses_say_they_are_fragments: now includes codex, pi - Added check: no harness snippet/instructions say 'starts' or 'launch' - every_section_is_on_exactly_one_tab: updated heading expectation Five of six harnesses support mid-session reload; only Claude Code needs session restart. Co-authored-by: Oded Messer <odedmesser@gmail.com>
Why
Draft PR #599 implements Settings UI that generates MCP registration snippets for BYO harnesses. Since ai-buddy's MCP endpoint rotates port and token every launch, users need to reconfigure their harness each time.
#580 answered "how to initially register." This research answers "how to reconfigure when URL/token changes" — specifically:
AuthorizationbearerProduct constraint (Oded): Prefer MCP reconfiguration methods over harness launch CLIs. BYO means the user decides when/how/where to launch their Harness; ai-buddy only tells advanced users how to point that Harness at ai-buddy's MCP.
What Changed
New research doc:
docs/research/byo-harness-mcp-reload.mdCovers six harnesses (Claude Code, Codex, Hermes, OpenCode, Grok, Pi) with execution evidence where possible, docs citations otherwise. Each entry labeled Fact / Inference / Assumption.
Key Findings
1. Native Reload Support
/reload-mcp/reload/mcps+r/reload+/mcp reconnectmcpServer/refreshFive of six harnesses support mid-session reload. Only Claude Code requires full session restart (exit and re-run
claude).2. The Claude Code Re-Add Trap (Confirmed from #580)
Trap is unique to Claude Code. Other harnesses overwrite via config file edit (or behavior unknown but no trap documented).
3. All Support Bearer Token
Every harness supports custom
Authorizationheaders via:--header "Authorization: Bearer <token>"headersmap withAuthorizationkeyConfirms #580: stdio shim never required for bearer auth.
4. Config File Locations (Summary)
~/.claude.json.mcp.jsonor.claude/config/local.json~/.codex/config.toml~/.hermes/config.yaml~/.config/opencode/opencode.jsoncopencode.jsonc~/.grok/config.toml.grok/config.toml~/.pi/agent/mcp.json.mcp.jsonRecommendations for #599 Settings UI
Generate Appropriate Snippet Per Harness
remove+add(omit-s, local default)export+codex mcp add --bearer-token-env-var(TOML alt)hermes mcp add --auth header(YAML alt)opencode mcp add --header(flat JSON alt)grok mcp add(default scope: user; optional--scope project)Include Reload Instructions
claude."mcpServer/refreshfrom your Codex session."/reload-mcpin your Hermes session."/reloadin your OpenCode session."/mcps, then pressrto reload."/reload, then/mcp reconnect ai-buddy."Claude Code Snippet Must Remove First (and Omit Scope)
Critical: Generated snippet for Claude Code must be:
The
2>/dev/nullsuppresses "not found" when entry doesn't exist yet.Scope: Omit
-sto use local default (project-scoped).-s useris optional only if the user wants the same entry in every project.Tooltip: Token Rotation
Suggested text: "The URL and token change every time ai-buddy launches. Re-run this command/snippet each time."
Comparison to #580
#580 answered: "How to initially register an MCP server with bearer auth?"
This research answers: "How to reconfigure after URL/token changes?"
Changes from #580's story:
Old #580 assumption: "maybe restart required everywhere." New finding: only Claude Code requires restart; others reload mid-session.
References
Out of Scope
Related Work
The per-Harness shapes written up in
docs/DEVELOPMENT.md→ Pointing a Harness you run yourself at ai-buddy already cover initial registration. This research adds the reconfiguration / reload layer on top.— Cursor agent (Coder), on @omesser's behalf.