Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

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. experimental is the API catalog’s label: the ALPN is off by default and the shape may change before it moves to public. The bound ask, per-call caps and the audit row are not built.
  • Scope: the bytes on ALPN vulpine/mcp/1 between 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, delegations and mcp all true. Otherwise the ALPN fails the TLS handshake.

Who may open it: a delegated key, admitted once

  1. 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, ALPN vulpine/mcp/1, the session’s kind as its service, a lifetime of at most 3,600 seconds (300 by default) and a nonce.
  2. The signer itself presents it on vulpine/delegate/1 with op 3 (“on behalf”; an owner ALPN). 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 answers ok or no <word>: limit when a cap is full, and behalf when the fresh key presents an MCP delegation itself (op 1).
  3. The fresh key dials vulpine/mcp/1 once. The admission is spent on that connection, and a second connection is closed with code 2. A connection that outlives its delegation by [reach] delegate_max_live is closed with code 6 (expired). Revoking the signer closes its live sessions with code 3.

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.

  1. The hello (shim, within 10 seconds, one len32 frame: a big-endian u32 length 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
    v 1
    kind the session’s kind; it must equal the delegation’s service: claude-code, codex, pi, grok, hermes or other
    label optional: a fleet label of at most 16 characters, spoken as “
    project optional: the shim’s keyed project tag, 8 bytes as 11 unpadded base64url characters. The helper never logs it
    resume optional: the previous accept’s resume secret, for a rollover (below)
    framing the framings the shim speaks, preferred first: len32, ndjson. Empty or absent means len32

    Unknown members are refused (hello). With no stream or no hello within the 10 seconds, the helper closes the connection with code 0; a hello over 4,096 bytes closes it with code 7.

  2. The answer (helper, one len32 frame). Either an accept:

    {"v":1,"lease_ok":true,"resume":"<22 base64url characters>","max_frame":65536,"framing":"len32","roll_in_s":3000}

    framing is the first of the shim’s framings the helper knows. max_frame is the session’s frame cap ([reach] mcp_max_frame: 65,536 by default, at most 262,144). resume is a fresh single-use secret (16 bytes). roll_in_s is 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, or 3 for a burned lease) and starts nothing:

    word why
    version v is not 1
    hello not JSON, an unknown member, a bad label or project tag, or no framing the helper knows
    kind kind differs from the delegation’s service
    grant the session’s gateway subject does not fit (agent/<machine>-<kind>, at most 32 characters)
    limit reserved for a cap (the session caps are checked at op 3)
    resume a resume secret that is malformed, unknown or spent, or a rollover admission without one
    gateway the helper has no connector command, or it would not start
  3. The session. Each later frame, in the accepted framing, is exactly one MCP JSON-RPC message, both ways, byte for byte:

    • len32: a big-endian u32 length and the message. A frame over max_frame closes the connection with code 7 (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 past max_frame closes the connection the same way, without buffering more than max_frame bytes.

    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:

  1. The signer presents a new delegation for a new fresh key with op 3 and the rollover flag. It counts against the signer’s live leases, never a free place.
  2. The new key dials and puts the last accept’s resume in its hello.
  3. 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 public v1 could not absorb takes vulpine/mcp/2.
  • v is 1 for this ALPN. An unknown v is refused (version).

See also

  • API surfaces: this ALPN’s row and its stability label.
  • ADR 0053.
  • runtime/reach: the helper’s switches.

Was this page helpful?