You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
spike(harness): How each Harness registers a BYO MCP server, and whether it can send a bearer token #580
Won't republish. Attempted as #752 (closed unmerged). Remote has no research/byo-harness-mcp / docs/byo-harness-registration branch. In-issue table + shipped Settings/docs are the record.
Checked for the leftover branch on GitHub (gone). Closing rather than reconstructing the note.
Research done. All five Harnesses covered, four of them verified by execution rather than read — claude 2.1.266, hermes 0.18.2, opencode 1.18.30 and grok 1.0.13 are installed here; codex is not and is documentation-only. (Owner update 2026-09-13: codex is now also installed on the owner machine — see issue body "What is already settled".)
Full write-up committed on the branch research/byo-harness-mcp as docs/research/byo-harness-mcp-registration.md (not pushed yet — say the word).
The decisive question: answered, and it is good news
Every one of the five can attach a custom Authorization header. The loopback URL is therefore reachable by all of them and the stdio shim is never required — it stays available as an alternative, but it costs an absolute binary path and buys nothing extra, so it should not be the default anywhere.
Three of the agents stood up mock servers reproducing ai-buddy's exact gate — 401 without the token, 405 on GET, 202 with an empty body for notifications — and confirmed a real connection. Two details that matter for mcp_http.rs specifically, both observed on the wire rather than assumed:
None of them sends an Origin header, so the DNS-rebinding refusal never trips.
Claude Code opens a GET /mcp SSE stream, gets our 405, and still reports ✔ Connected — our non-streaming Streamable HTTP is enough.
The prompting question: no mid-session registration, on all five
Correction (Architect / Oded, 2026-09-13): the earlier line "None of them exposes a register-a-server tool" was false / too broad. Several Harnesses expose a CLI to register servers, e.g.:
claude mcp add --transport http <server-name> <server-url>
hermes mcp add <server_name> (+ hermes mcp login <server> where auth is needed)
Those are real register-a-server surfaces. What they are not is an answer to the owner's prompting question ("tell the running Harness in chat and have it pick up the server this turn").
What still fails mid-session, on all five observed:
An MCP server list is assembled from configuration at process start; the model's tool list is fixed for the turn.
In-session slash / model builtins do not register a new server for the current turn: Claude Code's /mcp takes only [reconnect|enable|disable], opencode's builtins contain no MCP-register verb, grok's tool calls only reach already-enabled servers, codex's /mcp only lists.
A prompt can make an agent shell out to claude mcp add (or the hermes/grok equivalents), but that writes the same config the user would have pasted into and still needs a Harness restart before the server appears in the tool list.
So: a generated snippet (usually the CLI mcp add line), not a chat prompt. Which is what the Settings design already assumed. The snippet is the register-a-server tool for Harnesses that have a CLI — Settings should prefer that over implying registration is impossible.
One trap the generated snippet must handle
Re-adding an existing server name in Claude Code is silently ignored — it keeps the old URL and token and exits 0. Since our port and token are fresh per run, a snippet that only does claude mcp add leaves a stale entry that looks installed and cannot connect. It has to claude mcp remove first.
#577 was filed independently for the other half of this — actually surfacing the endpoint. Neither issue referenced the other, so to be explicit: #577 is the decision and the mechanism; this issue is the per-Harness knowledge that says what the mechanism must produce.#577 gates #579; this one now has its answer.
— Claude Code, on @omesser's behalf. — Correction: Cursor agent (Architect), on @omesser's behalf.
Verified by running --help on the owner Mac (Claude Code 2.1.270, Hermes 0.18.2, OpenCode 1.18.30, Grok CLI 1.0.30, Codex CLI 0.154.0). Docs cross-checked for YAML/JSON/TOML shapes. pi has no mcp subcommand and is out of this issue’s five.
Default product shape: generate the CLI mcp add line (or a short shell block) as the copy box. Prefer config-file paste only where the CLI is interactive or forces an env-var indirection the user must also set.
Comparison (easy-config surface)
Harness
Easy wrapper
Bearer how
Config home
Copy-box default
Extra instructions
claude
claude mcp add / remove / add-json
--header "Authorization: Bearer …"
user/local/project via -s; also ~/.claude.json / .mcp.json
CLI block (remove then add)
Re-add with same name is silently ignored — must remove first. Restart Claude Code after.
codex
codex mcp add
--bearer-token-env-var <ENV> (token not inlined on CLI)
~/.codex/config.toml[mcp_servers.*]
CLI + export (two lines)
Put <TOKEN> in the named env var in the same shell / login session before starting Codex. Or paste TOML with http_headers. Restart / new session.
hermes
hermes mcp add (--url, --auth header|oauth)
CLI --auth headerprompts interactively and stores into ~/.hermes/.env; non-interactive = YAML headers
~/.hermes/config.yaml → mcp_servers
YAML paste (non-interactive)
Optional: hermes mcp add ai-buddy --url '<URL>' --auth header then paste token at prompt. Then /reload-mcp or restart.
(Docs also allow bearer_token_env_var = "AI_BUDDY_MCP_TOKEN" / env_http_headers — prefer env form so the token isn’t sitting in the file across launches.)
hermes — YAML (preferred; CLI is interactive for header auth)
Claude special-case: always emit remove then add in the same copy block.
Codex special-case: either two-line export + mcp add, or document that the env var must be present when Codex starts.
Hermes special-case: prefer YAML paste; don’t pretend hermes mcp add --auth header is one non-interactive line.
Stdio shim: still not needed as default for any of the five (all can send Authorization). Keep as advanced fallback only.
Evidence tier: CLI flag surfaces = verified-by-running help output on owner Mac (2026-09-13). Config file shapes = verified-by-running paths present + docs for schema. Mid-session chat registration still no (prior comment); wrappers write config for the next session / reload.
Acceptance updates this fills:
Comparison table (bearer via wrapper, where registration lives, Settings snippet)
Exact text Settings must generate per Harness
Full write-up still only on local-only branch research/byo-harness-mcp — not on GitHub; say the word to push / open a research PR mirroring this table into docs/research/byo-harness-mcp-registration.md
Done (answers this spike blocked on): comparison table, prompting-vs-launch, and the Settings snippets are answered in-thread and implemented on main (BYO section for Claude / Codex / Hermes / OpenCode / Grok / Pi). Reload/reconfigure research also landed as docs/research/byo-harness-mcp-reload.md via #644.
Still open: the original registration write-up (docs/research/byo-harness-mcp-registration.md) was never pushed to GitHub — only the in-issue table + #644 reload doc. Checkbox Every claim marked as verified-by-running or read-only still tracks that publish step. Leaving this open for that leftover; the Settings work is no longer blocked.
Shipped (research, not the registration write-up):
docs/research/byo-harness-mcp-reload.md now has §6, Prompting Is Not a Route — formal answer that mid-session chat cannot register an MCP server (Claude Code / Hermes / OpenCode / Grok / Codex; Pi not examined).
docs/research/byo-harness-mcp-registration.md is still not on GitHub (only the in-issue table + reload doc). The acceptance checkbox Every claim marked as verified-by-running or read-only still tracks that publish step.
Shipped (docs only): eight-line comment above the OpenCode arm of byo_registration() in settings.rs — why restart is required (config read once / cached; measured on OpenCode 1.18.30 via GET /mcp + GET /config), and that /reload came from open feature request sst/opencode#6719, not a shipped command. No behaviour change; user-facing after-steps were already corrected by #756 / #751.
Still open on this spike:docs/research/byo-harness-mcp-registration.md still not on GitHub. Acceptance checkbox Every claim marked as verified-by-running or read-only still tracks that publish step.
#895 merged and recovered docs/research/byo-harness-mcp-registration.md from closed #752 @ 97d7a54 (archival banner points at current Settings BYO / DEVELOPMENT / byo-harness-mcp-reload.md).
That supersedes the earlier close note’s “Won’t republish” row for this file. Spike acceptance was already met (in-issue table + #599 Settings + reload research); this is archival recovery only. Leaving this issue closed as completed.
Activity
omesser commentedon Sep 9, 2026
Research done. All five Harnesses covered, four of them verified by execution rather than read —
claude2.1.266,hermes0.18.2,opencode1.18.30 andgrok1.0.13 are installed here;codexis not and is documentation-only. (Owner update 2026-09-13:codexis now also installed on the owner machine — see issue body "What is already settled".)Full write-up committed on the branch
research/byo-harness-mcpasdocs/research/byo-harness-mcp-registration.md(not pushed yet — say the word).The decisive question: answered, and it is good news
Every one of the five can attach a custom
Authorizationheader. The loopback URL is therefore reachable by all of them and the stdio shim is never required — it stays available as an alternative, but it costs an absolute binary path and buys nothing extra, so it should not be the default anywhere.Three of the agents stood up mock servers reproducing ai-buddy's exact gate — 401 without the token, 405 on
GET, 202 with an empty body for notifications — and confirmed a real connection. Two details that matter formcp_http.rsspecifically, both observed on the wire rather than assumed:Originheader, so the DNS-rebinding refusal never trips.GET /mcpSSE stream, gets our405, and still reports✔ Connected— our non-streaming Streamable HTTP is enough.The prompting question: no mid-session registration, on all five
Correction (Architect / Oded, 2026-09-13): the earlier line "None of them exposes a register-a-server tool" was false / too broad. Several Harnesses expose a CLI to register servers, e.g.:
claude mcp add --transport http <server-name> <server-url>hermes mcp add <server_name>(+hermes mcp login <server>where auth is needed)grok mcp add --transport http <server-name> <server-url>Those are real register-a-server surfaces. What they are not is an answer to the owner's prompting question ("tell the running Harness in chat and have it pick up the server this turn").
What still fails mid-session, on all five observed:
/mcptakes only[reconnect|enable|disable], opencode's builtins contain no MCP-register verb, grok's tool calls only reach already-enabled servers, codex's/mcponly lists.claude mcp add(or the hermes/grok equivalents), but that writes the same config the user would have pasted into and still needs a Harness restart before the server appears in the tool list.So: a generated snippet (usually the CLI
mcp addline), not a chat prompt. Which is what the Settings design already assumed. The snippet is the register-a-server tool for Harnesses that have a CLI — Settings should prefer that over implying registration is impossible.One trap the generated snippet must handle
Re-adding an existing server name in Claude Code is silently ignored — it keeps the old URL and token and exits 0. Since our port and token are fresh per run, a snippet that only does
claude mcp addleaves a stale entry that looks installed and cannot connect. It has toclaude mcp removefirst.Relationship to #577
#577 was filed independently for the other half of this — actually surfacing the endpoint. Neither issue referenced the other, so to be explicit: #577 is the decision and the mechanism; this issue is the per-Harness knowledge that says what the mechanism must produce. #577 gates #579; this one now has its answer.
— Claude Code, on @omesser's behalf.
— Correction: Cursor agent (Architect), on @omesser's behalf.
omesser commentedon Sep 13, 2026
Easy-configuration wrappers — Settings snippet table (filled 2026-09-13)
Verified by running
--helpon the owner Mac (Claude Code2.1.270, Hermes0.18.2, OpenCode1.18.30, Grok CLI1.0.30, Codex CLI0.154.0). Docs cross-checked for YAML/JSON/TOML shapes.pihas nomcpsubcommand and is out of this issue’s five.Placeholders:
<URL>= ai-buddy loopback MCP URL,<TOKEN>= current-run bearer,ai-buddy= suggested server name.Default product shape: generate the CLI
mcp addline (or a short shell block) as the copy box. Prefer config-file paste only where the CLI is interactive or forces an env-var indirection the user must also set.Comparison (easy-config surface)
claudeclaude mcp add/remove/add-json--header "Authorization: Bearer …"-s; also~/.claude.json/.mcp.jsonremovefirst. Restart Claude Code after.codexcodex mcp add--bearer-token-env-var <ENV>(token not inlined on CLI)~/.codex/config.toml[mcp_servers.*]<TOKEN>in the named env var in the same shell / login session before starting Codex. Or paste TOML withhttp_headers. Restart / new session.hermeshermes mcp add(--url,--auth header|oauth)--auth headerprompts interactively and stores into~/.hermes/.env; non-interactive = YAMLheaders~/.hermes/config.yaml→mcp_servershermes mcp add ai-buddy --url '<URL>' --auth headerthen paste token at prompt. Then/reload-mcpor restart.opencodeopencode mcp add--header Authorization=Bearer…~/.config/opencode/opencode.json(or projectopencode.json)"oauth": falsein JSON if OpenCode tries OAuth first. Restart OpenCode.grokgrok mcp add--header "Authorization: Bearer …"(repeatable); expands${VAR}~/.grok/config.tomlor project.grok/config.toml(--scope)/mcpsrefresh). Prefer${AI_BUDDY_MCP_TOKEN}if you don’t want the raw token in shell history.Exact snippets Settings should generate
claude— CLI (preferred)Alt JSON one-shot:
codex— CLI + env (preferred)Alt TOML (
~/.codex/config.toml):(Docs also allow
bearer_token_env_var = "AI_BUDDY_MCP_TOKEN"/env_http_headers— prefer env form so the token isn’t sitting in the file across launches.)hermes— YAML (preferred; CLI is interactive for header auth)Merge under existing
mcp_serversin~/.hermes/config.yaml. Thenhermes mcp test ai-buddy(optional) and/reload-mcpor restart.Interactive CLI alternative:
opencode— CLI (preferred)Alt JSON (
opencode.json); setoauth: falseso a static bearer isn’t overridden by OAuth discovery:{ "mcp": { "ai-buddy": { "type": "remote", "url": "<URL>", "enabled": true, "oauth": false, "headers": { "Authorization": "Bearer <TOKEN>" } } } }grok— CLI (preferred)Env-expanded variant (keeps token out of history if already exported):
Product notes for #577 / Settings
removethenaddin the same copy block.export+mcp add, or document that the env var must be present when Codex starts.hermes mcp add --auth headeris one non-interactive line.Authorization). Keep as advanced fallback only.Acceptance updates this fills:
research/byo-harness-mcp— not on GitHub; say the word to push / open a research PR mirroring this table intodocs/research/byo-harness-mcp-registration.md— Cursor agent (Architect), on @omesser's behalf.
fix(docs): Align byo-harness-mcp-reload.md generate tables to locked #…
omesser commentedon Sep 15, 2026
Status after #599 merged:
Done (answers this spike blocked on): comparison table, prompting-vs-launch, and the Settings snippets are answered in-thread and implemented on
main(BYO section for Claude / Codex / Hermes / OpenCode / Grok / Pi). Reload/reconfigure research also landed asdocs/research/byo-harness-mcp-reload.mdvia #644.Still open: the original registration write-up (
docs/research/byo-harness-mcp-registration.md) was never pushed to GitHub — only the in-issue table + #644 reload doc. Checkbox Every claim marked as verified-by-running or read-only still tracks that publish step. Leaving this open for that leftover; the Settings work is no longer blocked.— Cursor agent, on @omesser's behalf.
omesser commentedon Sep 15, 2026
Partial landing from #743 on
main:Shipped (research, not the registration write-up):
docs/research/byo-harness-mcp-reload.mdnow has §6, Prompting Is Not a Route — formal answer that mid-session chat cannot register an MCP server (Claude Code / Hermes / OpenCode / Grok / Codex; Pi not examined)./reloadis an open feature request (sst/opencode#6719), not a shipped command. Summary / reload tables and the feat(settings): Generate the MCP registration for a Harness you run yourself #599 recommendation now say restart for OpenCode.Still open on this spike:
docs/research/byo-harness-mcp-registration.mdis still not on GitHub (only the in-issue table + reload doc). The acceptance checkbox Every claim marked as verified-by-running or read-only still tracks that publish step./reload(from feat(settings): Generate the MCP registration for a Harness you run yourself #599); research now says restart — tracked separately.Leaving this open.
— Cursor agent (Coder), on @omesser's behalf.
omesser commentedon Sep 16, 2026
Partial landing from #757 on
main(aef90cf):Shipped (docs only): eight-line comment above the OpenCode arm of
byo_registration()insettings.rs— why restart is required (config read once / cached; measured on OpenCode 1.18.30 viaGET /mcp+GET /config), and that/reloadcame from open feature requestsst/opencode#6719, not a shipped command. No behaviour change; user-facing after-steps were already corrected by #756 / #751.Still open on this spike:
docs/research/byo-harness-mcp-registration.mdstill not on GitHub. Acceptance checkbox Every claim marked as verified-by-running or read-only still tracks that publish step.Leaving this open.
— Cursor agent (Coder), on @omesser's behalf.
omesser commentedon Sep 22, 2026
Hygiene after #895
#895 merged and recovered
docs/research/byo-harness-mcp-registration.mdfrom closed #752 @97d7a54(archival banner points at current Settings BYO / DEVELOPMENT /byo-harness-mcp-reload.md).That supersedes the earlier close note’s “Won’t republish” row for this file. Spike acceptance was already met (in-issue table + #599 Settings + reload research); this is archival recovery only. Leaving this issue closed as completed.
— Cursor agent (Coder), on @omesser's behalf.