Skip to content

docs(research): BYO Harness MCP reconfiguration and reload - #644

Merged
omesser merged 4 commits into
mainfrom
cursor/byo-harness-mcp-reload-research-b0ab
Sep 15, 2026
Merged

omesser merged 4 commits into
mainfrom
cursor/byo-harness-mcp-reload-research-b0ab

Conversation

@omesser

@omesser omesser commented Sep 12, 2026 •

Copy link
Copy Markdown
Owner

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:

  1. How to add HTTP MCP server with custom Authorization bearer
  2. How to reload after config changes (without full restart if possible)
  3. Does re-add of existing name keep stale URL/token?
  4. What should ai-buddy generate: CLI snippet, config fragment, or both?

Product 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.md

Covers 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

Has Native Reload Harness Method
✅ Yes Hermes /reload-mcp
✅ Yes OpenCode /reload
✅ Yes Grok /mcps + r
✅ Yes Pi /reload + /mcp reconnect
✅ Yes Codex mcpServer/refresh
❌ No Claude Code Must restart session

Five 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)

claude mcp add --transport http \
  --header "Authorization: Bearer token1" \
  ai-buddy "http://127.0.0.1:58819/mcp"

# ai-buddy restarts (new port, new token)
claude mcp add --transport http \
  --header "Authorization: Bearer token2" \
  ai-buddy "http://127.0.0.1:61234/mcp"

# Result: EXIT 0, prints "Server already exists"
# BUT: Config keeps OLD values (port 58819, token1)

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 Authorization headers via:

  • CLI flag: --header "Authorization: Bearer <token>"
  • Config field: headers map with Authorization key

Confirms #580: stdio shim never required for bearer auth.

4. Config File Locations (Summary)

Harness User/Global Project
Claude Code ~/.claude.json .mcp.json or .claude/config/local.json
Codex ~/.codex/config.toml —
Hermes ~/.hermes/config.yaml —
OpenCode ~/.config/opencode/opencode.jsonc opencode.jsonc
Grok ~/.grok/config.toml .grok/config.toml
Pi ~/.pi/agent/mcp.json .mcp.json

Recommendations for #599 Settings UI

Generate Appropriate Snippet Per Harness

Harness Generate Why
Claude Code CLI with remove + add (omit -s, local default) Must remove first to avoid re-add trap
Codex CLI with export + codex mcp add --bearer-token-env-var (TOML alt) PRIMARY: CLI with environment variable
Hermes CLI hermes mcp add --auth header (YAML alt) PRIMARY: CLI with interactive token prompt
OpenCode CLI opencode mcp add --header (flat JSON alt) PRIMARY: CLI command
Grok CLI grok mcp add (default scope: user; optional --scope project) CLI overwrites in place; default scope is user
Pi Config JSON fragment No CLI available; file-based only

Include Reload Instructions

Harness Reload Instruction
Claude Code "Exit your Claude session and start a new one with claude."
Codex "Run mcpServer/refresh from your Codex session."
Hermes "Run /reload-mcp in your Hermes session."
OpenCode "Run /reload in your OpenCode session."
Grok "Run /mcps, then press r to reload."
Pi "Run /reload, then /mcp reconnect ai-buddy."

Claude Code Snippet Must Remove First (and Omit Scope)

Critical: Generated snippet for Claude Code must be:

claude mcp remove ai-buddy 2>/dev/null
claude mcp add --transport http ai-buddy \
  "http://127.0.0.1:<port>/mcp" \
  --header "Authorization: Bearer <token>"

The 2>/dev/null suppresses "not found" when entry doesn't exist yet.

Scope: Omit -s to use local default (project-scoped). -s user is 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:

  • Reload is possible on 5/6 harnesses (not "restart assumed" for all)
  • Config snippets viable for most (not just CLI)
  • Claude Code trap confirmed: re-add silently keeps stale values

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.

Open in Web Open in Cursor 

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>
cursor Bot pushed a commit that referenced this pull request Sep 12, 2026
…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>
cursor Bot pushed a commit that referenced this pull request Sep 13, 2026
…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 omesser left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>
@cursor

cursor Bot commented Sep 15, 2026

Copy link
Copy Markdown

Generate Tables Aligned to #599 Spec

Corrected docs/research/byo-harness-mcp-reload.md generate tables to match the locked Spec at #599 tip (67596ae). Stale rows updated as follows:

What Changed

Harness Was (Stale) Now (Locked Spec)
Claude Generated claude mcp add -s user Omit -s (local default); optional -s user only in steps
Codex Config TOML fragment with headers as PRIMARY CLI export + codex mcp add --bearer-token-env-var as PRIMARY; TOML alt uses http_headers
Hermes Config YAML fragment as PRIMARY CLI hermes mcp add --auth header (interactive token) as PRIMARY; YAML alt
OpenCode Config nested mcp.servers.<name> with type: "http" CLI opencode mcp add --header as PRIMARY; JSON alt flat type:remote + oauth:false (NOT nested)
Grok No scope default noted Default scope is current project; --scope user optional

What Stayed

  • Reload research findings (all accurate)
  • Re-add trap for Claude (silently keeps stale)
  • Reload mechanisms per harness
  • Config locations and alternative formats

Verification

Aligned 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.

@omesser

omesser commented Sep 15, 2026

Copy link
Copy Markdown
Owner Author

Architect gate: CHANGES_REQUESTED @ a6b515d (still draft)

Tip move addressed most of the prior gate. Claude / Codex / Hermes / OpenCode generate tables now match locked #599 Spec (byo_registration on #599 tip 73cca08). Reload research stays valuable. One blocker remains — do not CLEARED / undraft yet.

Cleared vs prior gate

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 project only 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 user for 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 user snippet). 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>
@cursor

cursor Bot commented Sep 15, 2026

Copy link
Copy Markdown

Grok Default Scope Corrected

Fixed leftover error at b2aff7c: Grok default scope is user (not project), per Architect locked Spec (live CLI verification).

Corrected

  • Summary table: "default scope: user"
  • Generate section: "Default scope is user (all projects); use --scope local for current project only"
  • Recommendations: "default scope: user"

Config file locations unchanged (.grok/config.toml is still project-scoped as a file location).

— Cursor agent (Coder), on @omesser's behalf.

@omesser

omesser commented Sep 15, 2026

Copy link
Copy Markdown
Owner Author

Architect gate: CHANGES_REQUESTED @ b2aff7c (still draft)

Tip fixed the inverted default (user ✓). One blocker remains — do not CLEARED / undraft yet.

Cleared vs prior gate

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 project only 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

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>
@cursor

cursor Bot commented Sep 15, 2026

Copy link
Copy Markdown

Grok Optional Flag Corrected

Fixed at 69f1c6c: Grok optional override is --scope project (not --scope local), per Architect exact wording.

Grok instructions now correctly state: "Default scope is user (all projects); use --scope project for current project only."

— Cursor agent (Coder), on @omesser's behalf.

@omesser

omesser commented Sep 15, 2026

Copy link
Copy Markdown
Owner Author

Architect gate: CLEARED @ 69f1c6c (still draft)

Tip fixed the last blocker (--scope project). Generate tables now match locked #599 Spec (byo_registration @ 73cca08). Reload research stays valuable.

Cleared vs Spec

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)

Draft may undraft when you’re happy with the body. Architect never merges.

— Cursor agent (Architect), on @omesser's behalf.

@omesser omesser left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Architect gate: CLEARED @ 69f1c6c (draft)

Generate tables now match locked #599 / #580 Spec:

  • Claude: remove-before-add, omit -s, optional -s user in instructions only
  • Codex: export + --bearer-token-env-var primary; TOML http_headers alt
  • Hermes: hermes mcp add … --auth header primary; YAML alt
  • OpenCode: CLI --header primary; flat type: remote + oauth: false alt
  • Grok: default user; optional --scope project (prior local nit 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.

@cursor
cursor Bot marked this pull request as ready for review September 15, 2026 00:46
@cursor

cursor Bot commented Sep 15, 2026

Copy link
Copy Markdown

PR body refreshed to match tip spec:

  • Claude: omit -s / remove-before-add
  • Codex: CLI+env primary + http_headers alt
  • OpenCode: CLI primary + flat type:remote
  • Hermes: CLI primary + YAML alt
  • Grok: default user + optional --scope project

Removed stale rows (old -s user / nested http / YAML-primary / Grok project-default).

Undrafted and ready for review.

— Cursor agent (Coder), on @omesser's behalf.

@omesser
omesser merged commit d86d770 into main Sep 15, 2026
5 checks passed
@omesser omesser added documentation Improvements or additions to documentation research Defining or executing a research into an aspect: tech, direction, decision harness labels Sep 15, 2026
@omesser

omesser commented Sep 15, 2026

Copy link
Copy Markdown
Owner Author

Merged @ d86d770. Left a pointer on #599.

— Cursor agent (Coder), on @omesser's behalf.

cursor Bot pushed a commit that referenced this pull request Sep 15, 2026
…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>
cursor Bot pushed a commit that referenced this pull request Sep 15, 2026
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation harness research Defining or executing a research into an aspect: tech, direction, decision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants