docs(mcp)!: mcp-v4, a second transport, and what its token is not

The contract said "stdio, and only stdio" and now describes two
transports, so it gets a version -- **v4**, because v3 (the live stream)
was published to main while this branch was in review.  Nothing here
breaks: no tool renamed, no argument reshaped, no resource moved, so a
client written against v2 over stdio still works unchanged.  v2 is the
only bump that took something away, and it took away five tools; v3 and
v4 are additive.

§1 is rewritten around the asymmetry rather than around the feature,
because the asymmetry is the part that is easy to get wrong later: stdio
is unauthenticated **on purpose** and that is now written down with its
argument, so the next reader does not "fix" it.  A stdio client spawns
the server, so it has already passed a filesystem permission check and
holds the broker's 0660 control socket either way -- unix permissions are
the gate, exactly as `mcp.enable`'s own option text has always said.  A
port is the first time the caller passed neither, which is the entire
reason the token exists.

§2 gains `HHSTREAM_MCP_STATE_DIR` (and why it is NOT `sessions.stateDir`:
that directory is 0700 owned by the broker's user and holds the audit
trail), the `serve --http` flags, and the `token` verbs with the three
decisions behind them -- digests not tokens, wall-clock expiry where
every broker deadline is BOOTTIME, and a flock because two processes
write the table.  §3 records that a token's toolsets intersect the
server's and cannot widen them.

§10 is new and is the part worth having: **what this is not.**  Not OAuth
2.1, not RFC 9728, no metadata discovery -- so a client that can only
*discover* an authorization server will not connect, and one that lets
you set a header will.  And a token narrows tools but not resources, so a
`frames` token can still read `hhstream://sessions`.  Both are now TODO
files with their own evidence and recommended routes, beside the two
limits the SDK imposes:

* `mcp-http-auth-is-not-oauth.md` -- medium, and the severity is about
  interoperability rather than exposure.  Nothing is weaker than it
  claims; what is missing is the part that lets a client somebody else
  configured connect without a human pasting a header.  It records that
  `ssh host hhstream-mcp` is genuinely the better answer for one operator
  with one machine, because that is what this competes with.
* `mcp-tokens-do-not-scope-resources.md` -- medium, and nothing at all
  until a second token is minted for someone else, at which point the
  restriction is narrower than it reads.

README gains the HTTP section with the three things to know before
enabling it (the unit's refusal and self-heal, no TLS, not OAuth);
README.dev gains the token commands in the dev-shell walkthrough and the
new check's row; ARCHITECTURE gains the two transports in its diagram and
the reason the shim has a state directory while owning no state about the
desktop.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-12 18:00:05 +00:00
1 parent 7eb9afdfa3
commit 10176356b6
8 files changed
+504 -31

No files matched your search

+28 -3
View File
@@ -51,10 +51,21 @@ import the SDK:
```bash
nix develop
hhstream-mcp --list-tools # the 21 acting verbs
hhstream-mcp --list-tools # the 23 acting verbs
hhstream-mcp --list-resources # the 10 read-only URIs
# the HTTP transport, which is the only part that needs a credential
export HHSTREAM_MCP_STATE_DIR=$PWD/.mcp-state
hhstream-mcp token mint --label dev # the token, once, on stdout
hhstream-mcp serve --http # 127.0.0.1:9989/mcp
```
stdio is unauthenticated on purpose and the HTTP transport is not: a stdio
client spawns the server and so already holds the broker's socket, while a port
is reachable by someone who passed no permission check. `docs/CONTRACT-mcp.md`
§1 has the argument; `token mint` prints the secret once and the table on disk
keeps only its digest.
## The checks
| Check | What it proves | Needs a VM |
@@ -72,6 +83,8 @@ hhstream-mcp --list-resources # the 10 read-only URIs
| `vm-stream-firewall` | the stream's **port**: the guest's own running firewall accepts the configured port and not the module's default, a peer outside the guest reaches it, and is refused on a port beside it that was never opened | yes |
| `vm-mcp` | the **MCP server over stdio**: `mcp.enable` puts the binary on PATH and starts no unit, the `initialize` handshake completes over a real pipe, all 23 tools and 10 resources are listed with their annotations and their two rules, both a tool call and a resource read reach the live broker and return its own protocol object, two reads of a session do **not** move its idle deadline while `session_touch` does, a frame arrives as a blob at exactly its output's configured size, the pointer lease is granted/used/returned against the real driver, `--toolsets` narrows the tools and leaves the resources alone, and a refusal arrives as a tool error (or, for a read, a protocol error) carrying the frozen exit code | yes |
| `vm-mcp-http` | the **HTTP transport, its token and its unit**: the unit refusing to start while the authorization table is empty *and* saying so in the journal, then coming up by itself within one retry interval of the first `token mint` with no `systemctl start` — the half that nothing in Python can test; the state directory `0700` and owned by the account that mints tokens, the table `0600` and holding no token; the port on loopback only and **not** in the firewall; an unauthenticated and a wrong-token request both `401` with an empty body and no echo; a good token completing the handshake, reading a resource and calling a tool against the live broker; two tokens served by **one process** with different tool budgets; and a revocation taking effect on the next request with no restart | yes |
All of them at once:
```bash
@@ -96,6 +109,7 @@ nix build -L .#checks.x86_64-linux.vm-keyboard
nix build -L .#checks.x86_64-linux.vm-keyboard-de
nix build -L .#checks.x86_64-linux.vm-stream-firewall
nix build -L .#checks.x86_64-linux.vm-mcp
nix build -L .#checks.x86_64-linux.vm-mcp-http
nix build -L .#checks.x86_64-linux.vm-stream
```
@@ -125,11 +139,15 @@ output is on that path beside it, and `mcp` is in the test environment, because
— not optionally: a file that skipped when the SDK was absent would be green in
exactly the build where a malformed tool schema mattered.
The MCP suite is four files, split along what each can be tested without:
The MCP suite is six files, split along what each can be tested without:
`test_mcp_invoke.py` (the in-process CLI call and the exit-code mapping),
`test_mcp_tools.py` (the argv each tool builds, and the toolsets),
`test_mcp_resources.py` (URI routing, query parameters, and that a read never
writes) and `test_mcp_server.py` (the SDK wiring, over its memory transport).
writes), `test_mcp_authorizations.py` (the token store and the `token` verbs --
standard library, no SDK), `test_mcp_server.py` (the SDK wiring, over its
memory transport, plus the command line now that it has subcommands) and
`test_mcp_http.py` (the bearer check and the per-token toolsets, over a real
ASGI stack).
The check fails if the suite is **empty**, not just if it is red. `pytest` exits
5 on "collected nothing", but it exits 0 when every test was skipped or
@@ -264,11 +282,18 @@ checks/
vm-stream-firewall.nix nixosTest, the stream's port in the guest's firewall
vm-mcp.nix nixosTest, hhstream-mcp driven over stdio by a raw
JSON-RPC client against the live broker
vm-mcp-http.nix nixosTest, the HTTP transport: the unit's refusal while
no token exists and its self-heal after the first mint,
the 0700 state dir, the refusals, and two tokens with
different tool budgets served by one process
vm-stream.nix nixosTest, `session stream enable` and a real HTTP
viewer reading MJPEG from inside the guest
lib/mcp_client.py that client: hhs-mcp-call, stdlib only and deliberately
NOT the MCP SDK's -- the SDK on both ends would agree
with itself about a framing neither side had to get right
lib/mcp_http_client.py the same choice over HTTP: hhs-mcp-http, urllib only,
with a distinct exit status for an HTTP refusal so a
401 cannot be mistaken for a server that died
lib/test-tools.nix packages the tests/ helpers for the guest
lib/session-tools.nix packages the two guest programs below
lib/session-machine.nix the guest the three session checks share