Skip to content

fix(mcp): Serve MCP from the app on loopback HTTP so a Harness's speak lands on screen (#470) - #491

Merged
omesser merged 3 commits into
mainfrom
fix/470-mcp-real-instance-deps
Sep 8, 2026
Merged

omesser merged 3 commits into
mainfrom
fix/470-mcp-real-instance-deps

Conversation

@omesser

@omesser omesser commented Sep 7, 2026

Copy link
Copy Markdown
Owner

Closes #470 for the loopback path. A Harness's speak now reaches the buddy's bubble. #166 named this as its known blocker and #16 was closed on the promise to fix it.

A real Harness's line in the buddy's bubble

That is the exact string a real Claude Code process passed to speak, drawn by the overlay. The shot is cropped to the bubble.

The transport decision

The app serves MCP itself on loopback HTTP, and ai-buddy-mcp stays the unchanged stdio fallback. #166 offered that or a shim that dials the app, and this is the smaller of the two: either way the endpoint has to live inside the app, because the roster is the handle the tools need and has no out-of-process form. Serving it directly needs no shim and no discovery file, since ACP's session/new already carries a URL and headers.

A plain listener and about two hundred lines rather than a web framework, because the specification permits a JSON response to a POST and nothing here streams. Recorded in the new ADR-0018, and ADR-0017's claim that there is no loopback server yet is replaced.

Security of the endpoint

  • Binds 127.0.0.1 on an ephemeral port.
  • Every request carries a bearer token of 32 fresh random bytes, in a header rather than the URL.
  • A request with an Origin header is refused outright, so a browser cannot reach it.
  • Anything other than POST is refused.
  • The endpoint type implements neither Debug nor Serialize, with a test that fails if either derive ever lands on it, so the token cannot reach a log by accident.

What was actually observed, end to end

  1. The app logged the MCP URL it was serving.
  2. The session/new on the wire carried that URL and an Authorization header.
  3. A real claude -p against that URL and token listed the live roster, returning the same Instance id the app's own traces use rather than the empty stub one, then called speak.
  4. Talk frames in the frame trace, and the bubble above.

Two honest limits

  • The attached session's own speak is gated by the permission click, by design. In the first run the attached Harness did call it, and the request was held with no Chat surface on screen until the turn timed out. Only a click there may answer, per ADR-0003 and ADR-0010, and a click cannot be scripted. So the tool surface is provably reachable by the attached Harness; answering it is the user's. The on-screen proof went through the identical endpoint, token and dispatch path from a second real process.
  • hermes still gets stubs. It advertises no HTTP capability, so it falls back to the stdio binary, whose roster is empty, and a speak there still returns success and moves nothing. That is now said plainly in the binary's own header and in ADR-0018, and closing it is the shim that Attaching real harnesses: per-harness MCP client config for Claude Code, opencode, Hermes, Pi, and Grok #166 owns.

How to verify

cargo test -p ai-buddy -- mcp_http:: harness:: acp_wire::

36 tests, thirteen new: the protocol, the token, origin and method gates, the no-Debug guard, a real socket round trip, the wire shape, and a speak reaching a frame's dialogue. cargo fmt --check, cargo clippy --workspace --all-targets -- -D warnings, cargo test --workspace, cargo test -p ai-buddy-mcp-server and pre-commit run --all-files all pass.

Notes for the reviewer

— Claude Code, on @omesser's behalf.

@omesser

omesser commented Sep 7, 2026

Copy link
Copy Markdown
Owner Author

Rebased onto main, which changed what this needed in two ways a clean rebase hid.

#497 landed on the same subject, making the app binary its own stdio MCP server when no sidecar is found. The two are halves of one thing and both restructured the same chooser, so the resolution keeps #497's launch shape and precedence byte for byte and puts the handshake decision above it. Precedence is now: a Harness that advertises the HTTP capability gets the app's loopback server with the live Instances, and anything else gets #497's chain of the environment override, then a sidecar, then the app binary re-executed. A session with no MCP server at all is no longer an outcome.

Both routes were re-run for real. With the sidecar moved aside, hermes registered seven tools over the app binary's own stdio server and reached end_turn. With it restored, claude was handed the loopback URL, and the attach record in the Action Log carries the URL with no token anywhere in it.

#505 renumbered the ADRs while this sat, which broke two things:

  • My new ADR was numbered 0018, and docs: supersede fat ADRs 0010/0013/0014/0017 (#495) #505 created its own 0018. The uniqueness hook would have failed. It is now ADR-0023, and every reference in code and docs follows.
  • My edits had gone into ADR-0017, which docs: supersede fat ADRs 0010/0013/0014/0017 (#495) #505 marked superseded. Editing a superseded record is editing history, so those edits are reverted. The live ADR gains a single pointer instead, and the detail it used to carry now sits where the new writing guideline puts it: the mechanism in ADR-0023, the precedence and the stub caveat in docs/DEVELOPMENT.md and in the MCP crate's own header.

While renumbering I also rewrote the ADR against that guideline, which explicitly excludes file paths, type names and issue narrative from an ADR. It is now half the length and states the architecture: tools are dispatched inside the running app because the layer owning the Instances cannot exist outside the process, and the transport follows from that. The stub fallback is named as a consequence rather than buried.

Verification after all of it: fmt, clippy with warnings denied, 299 tests in the shell and 455 in core, and every pre-commit hook including the ADR uniqueness one.

— Claude Code, on @omesser's behalf.

@omesser

omesser commented Sep 8, 2026

Copy link
Copy Markdown
Owner Author

Rebased onto cd15af01. It was 17 commits behind and conflicting; it is now three commits ahead and clean.

One conflict, in src-tauri/src/main.rs, and it was additive. main had gained app.manage(Mutex::new(session_log::Log::new())); at the same point where this branch adds the loopback server. The two are independent, so both are kept: session_log first, then the channel and mcp_http::serve, both still above attach — which is what this branch's own comment requires, since open_session reads the endpoint to decide what goes in session/new's mcpServers and the preflight thread can reach that within a tick.

Nothing else needed resolving. docs/adr/0023-app-dispatches-its-own-tools.md survived the rebase intact and the uniqueness hook passes — no ADR on main has taken 0023 in the meantime.

Verification after the rebase: 326 tests in the shell, 454 in core, 23 and 2 in the smaller crates, 0 failed. cargo clippy --all-targets -- -D warnings clean. Every pre-commit hook passes on the touched files, including the ADR uniqueness one.

Not re-run: the two live routes described in the comment above (hermes over the app binary's own stdio server, claude over loopback). The rebase touched neither the chooser nor the handshake, but that is reasoning, not evidence.

One thing to know for merge order. #501's branch turns the published ai-buddy-mcp binary into a shim that dials the endpoint this PR builds, and it is held until this lands. It does not become reachable the moment this merges: acp_wire::open here builds the entry as McpServerStdio::new("ai-buddy", path).args(...) with no env field, and harness.rs asserts the Harness child gets none of ours, so the hand-off that hands the shim its URL and token exists in neither branch. That is its own change with its own tests, on this branch or a follow-up. Detail in the comment on #501.

— Claude Code, on @omesser's behalf.

…k lands on screen

The stdio server built its DispatchContext from stubs, so a `speak` from an
attached Harness returned success and moved nothing. Dispatch now happens on
the frame loop, where the Roster is.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fix(mcp): An attached Harness's speak returns success and nothing appears on screen

1 participant