Reach: agent sessions
No paired row may hold mcp, and the helper closes any paired key on this ALPN with code 4 (role) before a byte, whatever its row says. A session's key is a fresh, throwaway iroh key:
Living doc, checked against the code 2026-11-14
reach-mcp.v1 — one agent session over reach: a delegated key, a hello, then MCP JSON-RPC both ways
- Status: accepted; experimental, built.
experimentalis the API catalog’s label: the ALPN is off by default and the shape may change before it moves topublic. The bound ask, per-call caps and the audit row are not built. - Scope: the bytes on ALPN
vulpine/mcp/1between an agent’s shim and the gateway host’s helper, and the admission that must come first. The MCP messages are MCP’s own (revision 2026-07-28), carried verbatim. They reach the agent connector (runtime/agent_link). - Schema: reach-mcp.v1.schema.json covers the hello, the accept and the refusal.
- Off by default. The helper serves it only with
[reach] enabled,delegationsandmcpalltrue. Otherwise the ALPN fails the TLS handshake.
Who may open it: a delegated key, admitted once
- An agent-signer row (paired with an attestation,
--may-delegate mcp) signs a delegation record. The record names the fresh key, the helper as audience, ALPNvulpine/mcp/1, the session’s kind as its service, a lifetime of at most 3,600 seconds (300 by default) and a nonce. - The signer itself presents it on
vulpine/delegate/1with op3(“on behalf”; anownerALPN). The helper checks the signature, the signer’s row, the times (60 s skew), the nonce, and the session caps (6 live sessions per signer, at most 16; 32 on the helper, at most 64). It answersokorno <word>:limitwhen a cap is full, andbehalfwhen the fresh key presents an MCP delegation itself (op1). - The fresh key dials
vulpine/mcp/1once. The admission is spent on that connection, and a second connection is closed with code2. A connection that outlives its delegation by[reach] delegate_max_liveis closed with code6(expired). Revoking the signer closes its live sessions with code3.
The record’s byte layout is in runtime/reach. It is an owner wire, so it may change
in any release: a third-party agent uses Vulpine’s shim (vulpine-reach mcp) or the
agent connector over HTTP.
The wire
The connection carries one bidirectional stream, opened by the shim.
-
The hello (shim, within 10 seconds, one
len32frame: a big-endianu32length and that many bytes of JSON, at most 4,096):{"v":1,"kind":"claude-code","label":"docs","project":"AbCdEfGhIjK","resume":null,"framing":["len32","ndjson"]}member v1kindthe session’s kind; it must equal the delegation’s service: claude-code,codex,pi,grok,hermesorotherlabeloptional: a fleet label of at most 16 characters, spoken as “ projectoptional: the shim’s keyed project tag, 8 bytes as 11 unpadded base64url characters. The helper never logs it resumeoptional: the previous accept’s resume secret, for a rollover (below) framingthe framings the shim speaks, preferred first: len32,ndjson. Empty or absent meanslen32Unknown members are refused (
hello). With no stream or no hello within the 10 seconds, the helper closes the connection with code0; a hello over 4,096 bytes closes it with code7. -
The answer (helper, one
len32frame). Either an accept:{"v":1,"lease_ok":true,"resume":"<22 base64url characters>","max_frame":65536,"framing":"len32","roll_in_s":3000}framingis the first of the shim’s framings the helper knows.max_frameis the session’s frame cap ([reach] mcp_max_frame: 65,536 by default, at most 262,144).resumeis a fresh single-use secret (16 bytes).roll_in_sis the seconds until the shim should roll over: five minutes before the connection’s live cap, or half the remaining life when that is under ten minutes.Or a refusal, after which the helper closes the connection (code
1, or3for a burned lease) and starts nothing:word why versionvis not1hellonot JSON, an unknown member, a bad label or project tag, or no framing the helper knows kindkinddiffers from the delegation’s servicegrantthe session’s gateway subject does not fit ( agent/<machine>-<kind>, at most 32 characters)limitreserved for a cap (the session caps are checked at op 3)resumea resume secret that is malformed, unknown or spent, or a rollover admission without one gatewaythe helper has no connector command, or it would not start -
The session. Each later frame, in the accepted framing, is exactly one MCP JSON-RPC message, both ways, byte for byte:
len32: a big-endianu32length and the message. A frame overmax_framecloses the connection with code7(limit) from its header alone, and the connector child is stopped.ndjson: MCP’s own stdio framing, one message per line. A line still open pastmax_framecloses the connection the same way, without buffering more thanmax_framebytes.
A message holding a raw newline is dropped and counted, never passed on (stdio’s rule). A session with no frame either way for 30 minutes is closed.
On the gateway’s host each session is one run of the connector’s stdio mode. Its subject, label, lease and project come from the helper’s view of the delegation, never from the agent’s bytes.
The rollover
A delegation lives at most an hour. A session outlives it by rolling over before roll_in_s runs out:
- The signer presents a new delegation for a new fresh key with op
3and the rollover flag. It counts against the signer’s live leases, never a free place. - The new key dials and puts the last accept’s
resumein its hello. - The helper answers a new accept with a new secret, moves the session (the same connector child) to the new stream,
lets the old connection drain for up to 2 seconds, and closes it with code
0.
A secret is honored once. A second use, or one from another signer, kind or project, burns the lease: the hello is
refused resume, the session’s live connection is closed with code 3 and its child stops.
Close codes
| code | |
|---|---|
0 |
done: the session ended, the old connection of a rollover, or no hello in time |
1 |
refused: after a refusal word |
2 |
unpaired: no admission, or the admission is spent |
3 |
revoked: the signer was revoked, or the lease burned |
4 |
role: a paired key on this ALPN |
6 |
expired: the connection outlived its delegation by delegate_max_live |
7 |
limit: a frame over max_frame, or a hello over 4,096 bytes |
What Vulpine’s own shim does (not normative)
vulpine-reach mcp --kind KIND [--label NAME] [--framing len32|ndjson] is a stdio MCP server to the agent host. It
dials on the host’s first message. With no session it answers each request itself with JSON-RPC error -32000 and
data.reason: "unreachable". It backs off 1 s, times 1.5 per failure, up to 15 s.
Compatibility
- Experimental: any of this may change in a release. A change that a
publicv1 could not absorb takesvulpine/mcp/2. vis 1 for this ALPN. An unknownvis refused (version).
See also
- API surfaces: this ALPN’s row and its stability label.
- ADR 0053.
- runtime/reach: the helper’s switches.