Skip to content

spike(harness): How each Harness registers a BYO MCP server, and whether it can send a bearer token #580

Closed

Description

@omesser

Closing as completed

Spike answers that blocked Settings are met. Nothing product-side waits on this ticket.

Acceptance Where it landed
Comparison table (bearer, stdio, registration locus, mid-session) In-issue comments (2026-09-09 / 2026-09-13)
Prompting vs launch In-issue + docs/research/byo-harness-mcp-reload.md §6 (#743)
Exact Settings snippets Implemented #599; documented #859 / DEVELOPMENT
Publish byo-harness-mcp-registration.md 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.

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

Activity

  1. added this to the V1 milestone on Sep 9, 2026
  2. omesser commented on Sep 9, 2026

    @omesser
    OwnerAuthor

    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)
    • 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:

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

    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.

  3. added
    researchDefining or executing a research into an aspect: tech, direction, decision
    on Sep 13, 2026
  4. omesser commented on Sep 13, 2026

    @omesser
    OwnerAuthor

    Easy-configuration wrappers — Settings snippet table (filled 2026-09-13)

    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.

    Placeholders: <URL> = ai-buddy loopback MCP URL, <TOKEN> = current-run bearer, ai-buddy = suggested server name.

    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 header prompts 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.
    opencode opencode mcp add --header Authorization=Bearer… ~/.config/opencode/opencode.json (or project opencode.json) CLI one-liner For static bearer, also set "oauth": false in JSON if OpenCode tries OAuth first. Restart OpenCode.
    grok grok mcp add --header "Authorization: Bearer …" (repeatable); expands ${VAR} ~/.grok/config.toml or project .grok/config.toml (--scope) CLI one-liner Restart / new session (or /mcps refresh). Prefer ${AI_BUDDY_MCP_TOKEN} if you don’t want the raw token in shell history.

    Exact snippets Settings should generate

    claude — CLI (preferred)

    claude mcp remove ai-buddy 2>/dev/null; \
    claude mcp add --transport http --header "Authorization: Bearer <TOKEN>" ai-buddy <URL>

    Alt JSON one-shot:

    claude mcp remove ai-buddy 2>/dev/null; \
    claude mcp add-json ai-buddy '{"type":"http","url":"<URL>","headers":{"Authorization":"Bearer <TOKEN>"}}'

    codex — CLI + env (preferred)

    export AI_BUDDY_MCP_TOKEN='<TOKEN>'
    codex mcp add ai-buddy --url '<URL>' --bearer-token-env-var AI_BUDDY_MCP_TOKEN

    Alt TOML (~/.codex/config.toml):

    [mcp_servers.ai-buddy]
    url = "<URL>"
    http_headers = { Authorization = "Bearer <TOKEN>" }

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

    mcp_servers:
      ai-buddy:
        url: "<URL>"
        headers:
          Authorization: "Bearer <TOKEN>"
        enabled: true

    Merge under existing mcp_servers in ~/.hermes/config.yaml. Then hermes mcp test ai-buddy (optional) and /reload-mcp or restart.

    Interactive CLI alternative:

    hermes mcp add ai-buddy --url '<URL>' --auth header
    # prompts for API key / Bearer token — paste <TOKEN> (raw token; Hermes adds Bearer)

    opencode — CLI (preferred)

    opencode mcp add ai-buddy --url '<URL>' --header "Authorization=Bearer <TOKEN>"

    Alt JSON (opencode.json); set oauth: false so 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)

    grok mcp add --transport http ai-buddy <URL> --header "Authorization: Bearer <TOKEN>"

    Env-expanded variant (keeps token out of history if already exported):

    export AI_BUDDY_MCP_TOKEN='<TOKEN>'
    grok mcp add --transport http ai-buddy <URL> --header "Authorization: Bearer ${AI_BUDDY_MCP_TOKEN}"

    Product notes for #577 / Settings

    1. One copy box per selected Harness — the “CLI (preferred)” block above; put config-file alts in the per-Harness extra-instructions panel.
    2. Tooltip already settled: token rotates every launch → pasted config goes stale.
    3. Claude special-case: always emit remove then add in the same copy block.
    4. Codex special-case: either two-line export + mcp add, or document that the env var must be present when Codex starts.
    5. Hermes special-case: prefer YAML paste; don’t pretend hermes mcp add --auth header is one non-interactive line.
    6. Stdio shim: still not needed as default for any of the five (all can send Authorization). Keep as advanced fallback only.
    7. 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

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

  5. omesser commented on Sep 15, 2026

    @omesser
    OwnerAuthor

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

    — Cursor agent, on @omesser's behalf.

  6. omesser commented on Sep 15, 2026

    @omesser
    OwnerAuthor

    Partial landing from #743 on main:

    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).
    • OpenCode mid-session reload corrected: config is read once at start; /reload is 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.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.
    • Product follow-up: Settings BYO after-steps for OpenCode still say run /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.

  7. omesser commented on Sep 16, 2026

    @omesser
    OwnerAuthor

    Partial landing from #757 on main (aef90cf):

    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.

    Leaving this open.

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

  8. moved this from Todo to Done in Fidgeton Sep 22, 2026
  9. omesser commented on Sep 22, 2026

    @omesser
    OwnerAuthor

    Hygiene after #895

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

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestneeds-triageMaintainer needs to evaluate this issueresearchDefining or executing a research into an aspect: tech, direction, decision

    Projects

    • Status
      Done

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions