---
title: "Reach: agent sessions"
description: "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:"
type: "living"
source: "docs/contracts/reach-mcp.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

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

   ```json
   {"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 "<label> on <machine>" |
   | `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:

   ```json
   {"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](/docs/reference/api-surfaces): this ALPN's row and its stability label.
- ADR 0053.
- runtime/reach: the helper's switches.
