Remote MCP Edge

The fullest single-process node

chio mcp serve-http puts more into one process than any other Chio entry point: an HTTP and SSE edge for the MCP Streamable HTTP transport, three bearer authentication modes, an optional OAuth authorization server of its own, an admin API, and one kernel per session. Point it at --receipt-db and every governed action a remote client takes lands a signed receipt on this node’s disk. Omit both that flag and --control-url and the kernel refuses to dispatch at all unless policy sets allow_ephemeral_receipt_log, in which case the log is in memory and gone at restart. The crate is chio-mcp-remote, marked public_entrypoint = true in its Cargo.toml, and exposed as a single blocking call: serve_http(RemoteServeHttpConfig). The release runbook covers it as a supported self-hosted service alongside chio trust serve.

It is shipped and it is bounded. The bounded operational profile grades hosted authorization with cnf and dedicated sessions as local-only: bounded request-time authorization and protected-resource admission, with no cross-node auth-code failover and no restart-safe replay guarantee. It grades static bearer, non-cnf tokens, and shared_hosted_owner compatibility-only, which is the posture the rest of this page keeps returning to.

What the process holds

RemoteAppState is cloned into every handler and holds eight things. Five of them are Option, and the None case is a configuration, not a fault.

One process, many kernels

spawn_session builds a whole kernel per session: it loads the policy again, opens the receipt store, configures the capability authority, issues that session’s default capabilities, registers the wrapped server as a tool server, and starts a dedicated OS thread running edge.serve_message_channels. The HTTP handler never touches that kernel directly; it sends JSON into an mpsc channel and reads events back off a 256-slot broadcast channel. That channel is the one lossy component on the page. A reader more than 256 events behind gets RecvError::Lagged, and every handler answers it the same way: log a warning with the skipped count and keep going. The skipped events are not recovered from the retained window, so a slow SSE consumer loses them outright.

Stores behave differently under that fan-out, and the difference matters. With durable admission on and no --control-url, budget, revocation, and admission-operation state come from one DurableAdmissionRuntime opened once at factory construction against <session-db>.admission, with its lock root at <...>.admission.locks and its kernel seed at <...>.admission.kernel.seed; those handles are cloned into every session kernel, so the serving-owner fence described in Node State on Disk applies once, to the process. Two configurations leave that path. --control-url swaps it for DurableAdmissionRuntime::open_remote, which provisions no local sidecar and still requires --session-db for its kernel seed. A policy with durable_admission_mode: off leaves no runtime at all, and then configure_revocation_store and configure_budget_store run per session, one handle each on the same file.

The receipt store never shares. configure_receipt_store runs per session and opens its own SqliteReceiptStore against the same --receipt-db path, so a hundred sessions are a hundred reader pools and a hundred group-commit writers on one file, serialized by SQLite’s own locking rather than by a single writer actor. Each open also blocks for up to 30 seconds in wait_for_writer_ready while its actor seeds a verified head, so session creation pays that cost per session, not once.

Boot, in order

serve_http_async is the whole sequence, and its order is load-bearing.

1. Bind first. The TCP listener binds before anything else, because the resolved local_addr is the default for the public base URL, which is in turn the default for the issuer, the resource indicator, and every metadata URL.
2. Discover the identity provider. A discovery URL, or a provider profile paired with an issuer, pulls the OIDC document. Its JWKS is resolved only when nothing else supplies keys: no static JWT key, no local seed file, no introspection URL. Both fetches go through the typed HttpEgressContract, and without a contract they fail closed rather than proceeding. The CLI builds that contract from the configured auth URLs alone: the scheme and authority allowlists hold exactly those URLs, loopback, link-local, and IPv6 unique-local targets are denied unless a configured URL is itself one of those, redirects cap at three, and the response caps at 1 MiB. When no auth URL is configured the CLI passes no contract at all, which is safe only because nothing then fetches. Node Egress Contract documents that contract in full, including the DNS re-check and the per-hop redirect validation this fetch runs under.
3. Resolve the auth mode. build_remote_auth_mode rejects four combinations before it picks one: static bearer with any OAuth flag, a local seed file with a static JWT key or external discovery or introspection, an introspection client id and secret not supplied together, and introspection alongside --auth-jwt-public-key. That last rule is narrower than it looks. Discovery plus introspection is accepted, and introspection wins: the discovery document is still fetched and still shapes the issuer and the metadata, no JWKS is resolved, and every token is validated by a call to the introspection endpoint.
4. Build and cross-validate metadata. When both documents exist, validate_chio_oauth_discovery_metadata_pair requires them to carry an identical chio_authorization_profile, with the expected schema and id, capability-subject binding, the Chio DPoP proof type advertised, and every remaining contract field (portable claim catalog, portable identity binding, governed authorization binding, request-time contract, resource binding, artifact boundary) equal to this binary’s own default profile. It also requires the protected resource to list the authorization server’s own issuer.
5. Claim the disk and restore. Constructing the factory provisions and takes the serving lock on the admission sidecar, unless --control-url sent that state to a control plane instead. Local durable admission with no --session-db is not a degraded mode, it is a boot failure: "durable admission mode requires a database so operations and tool outcomes survive restart". Then persisted session rows are loaded, restored one by one, and deleted when they fail restore.
6. Wrap and serve. The rate-limit layer is applied to the /mcp routes, then admin, discovery, and OAuth routes are added on top of that router, then shared hygiene wraps everything.

One hygiene default is deliberately turned off, and the code says why in its own words:

// The generic per-request timeout is left off here. The edge's GET and POST
// routes return Server-Sent Event streams that stay open indefinitely while a
// session waits for notifications, so a blanket request timeout would close a
// healthy idle stream with 408 and force resumable clients into reconnect
// churn. Request bodies are already bounded by `read_limited_mcp_post_body`,
// per-IP request rate is capped by the rate limiter, and the drain deadline
// bounds any stream still open at shutdown.

Everything else in ServeHygieneConfig::default() stands: a 25 second drain, 1024 concurrent requests shedding to 503, and 2048 simultaneously accepted connections, all covered by Node Lifecycle. One of those defaults is a hole worth naming: max_body_bytes defaults to None, so no global body cap is layered on. The 8 MiB ceiling below belongs to the /mcp POST handler alone; admin and OAuth form posts carry only whatever limit their axum extractor applies. Draining is the durability story here, because the receipt commit actor acknowledges an append only after the batch reaches WAL: once a request finishes, the receipt it wrote is already durable, and each session kernel lives behind a channel with no in-process handle left to flush.

One request, in order

A POST to /mcp runs every gate below in this order, and each returns before the next is attempted. GET skips the body and content-type gates; DELETE runs only origin, bearer, session id, and auth continuity, so a Ready check never stands between a valid token and a session teardown.

Two details in that list are easy to misread. The rate-limit key comes from the accepted socket, not from any header, which mcp_rate_limit_key_ignores_unverified_client_headers pins directly: behind a reverse proxy every client shares one key. And the auth-continuity check runs against a terminal session too, so a client holding the wrong token learns 403 rather than which terminal state the session reached.

Binding a token to its sender

Sender constraints live entirely in the token’s cnf claim. There are three, and a token may carry any combination:

#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
struct ChioSenderConstraintClaims {
    #[serde(default, skip_serializing_if = "Option::is_none", rename = "chioSenderKey")]
    chio_sender_key: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none", rename = "x5t#S256")]
    mtls_thumbprint_sha256: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none", rename = "chioAttestationSha256")]
    chio_attestation_sha256: Option<String>,
}

validate_sender_constraint_runtime enforces each one that is present. A token with no cnf passes the whole function untouched, which is precisely why non-cnf tokens are compatibility-only: nothing about them is bound to the caller.

DPoP

chioSenderKey is a hex Ed25519 public key, and the request must carry a DPoP header holding a base64url-encoded JSON DpopProof. The proof reuses the kernel’s mediated-call DPoP body rather than defining an HTTP-specific one, so its fields are repurposed and compared exactly:

let expected_action_hash = sha256_hex(HTTP_DPOP_ACTION_HASH_EMPTY);
if proof.body.capability_id != expected_binding_id
    || proof.body.tool_server != expected_target
    || proof.body.tool_name != expected_method
    || proof.body.action_hash != expected_action_hash
{
    return Err(
        "DPoP proof did not match the expected binding id, target, method, or action hash"
            .to_string(),
    );
}

The three expected values depend on where the proof is checked. On a /mcp request expected_binding_id is the token’s jti, expected_target is the protected resource indicator, and expected_method is that request’s HTTP method; a DPoP-bound token with no jti is refused for want of a binding identifier. At the local token endpoint the binding id is the authorization code itself, the target is {issuer}/token, and the method is always POST. The action hash is the SHA-256 of the empty string in both cases, because the HTTP proof binds no arguments. The proof must also declare schema chio.dpop_proof.v1, carry an agent_key equal to the bound chioSenderKey, carry a non-empty nonce, be signed by that key over the canonical JSON of its own body, sit inside the default 300-second TTL with at most 30 seconds of future skew, and win a single-use insert into a 65,536-entry nonce store keyed by nonce and binding id. A replayed nonce is rejected.

mTLS and runtime attestation

The other two constraints are header comparisons: x-chio-mtls-thumbprint-sha256 against x5t#S256, and x-chio-runtime-attestation-sha256 against chioAttestationSha256. Both are string equality, and a missing header is a refusal rather than a pass.

Streams and replay

Every event a session emits gets an id of {session_id}-{seq} from one monotonic counter, and is classified once, at emission: a message with a method and no id is a notification, anything else is request-correlated. Notifications, and only notifications, are pushed into a retained deque bounded at DEFAULT_NOTIFICATION_REPLAY_WINDOW = 64 entries.

A GET without Last-Event-ID attaches a live notification stream. A GET with one replays first. The cursor is parsed strictly, and every failure is a 409: an id that does not split on its final hyphen, an id whose session prefix belongs to another session, a non-numeric sequence, an empty retained window, or a sequence below one less than the oldest retained event or above the newest. Replay is best-effort-free: the edge refuses a cursor it can no longer prove rather than silently resuming from the oldest event it happens to hold. Nothing is persisted, so the window is per process: a restart drops it, and a restored session starts its counter at zero again.

Exactly one GET notification stream may be attached per session. The second gets 409, and the flag is released by a Drop guard when the stream ends. That single flag drives delivery routing: should_emit_post_stream_event emits notifications on a POST response only while no GET stream is attached, so a client that never opens the GET stream still receives notifications and a client that does opens no duplicate path. On a POST that carries a client notification rather than a request, the handler drains events until 100 milliseconds pass with none, so a session emitting steadily can hold that response open indefinitely; on a POST that carries a request, notifications go out inline until the terminal response. The POST request stream is serialized by an owned mutex, and the POST-side responses open with a priming event carrying a 1000 millisecond reconnect hint; the GET streams send no such hint. Every response is tagged with x-chio-mcp-response-mode, whose values name the exact branch taken: initialize_sse, post_request_sse, post_notification_sse, post_notification_accepted, get_sse_live, get_sse_replay.

The self-issued authorization server

Pointing --auth-server-seed-file at a seed turns the edge into its own OAuth 2.0 authorization server: GET and POST /oauth/authorize, POST /oauth/token, GET /oauth/jwks.json, and a discovery document advertising exactly two grants, authorization_code and urn:ietf:params:oauth:grant-type:token-exchange, with S256 as the only code challenge method and none as the only client authentication method.

The authorization request is validated tightly. Response type must be code, client id must be non-empty, the redirect URI must be https or a loopback http, the resource parameter is mandatory and must equal the advertised protected resource, and PKCE is not optional. Scope is the exception: with no --auth-scope configured, resolve_requested_scopes has nothing to check against and returns whatever the client asked for. Chio’s own request-time parameters are validated at the same point: authorization_details must contain at least one chio_governed_tool detail with non-empty locations and actions, any detail type outside the three Chio types is refused, no single detail may carry a sidecar belonging to another type (a governed-tool detail with commerce or metered-billing fields is rejected, and so is a commerce detail carrying metered billing), and a chio_transaction_context must carry a non-empty intent id and intent hash, with approval, runtime assurance, and call-chain fields each pulling in their own required companions. Attestation-bound senders are refused unless the evidence digest matches the transaction context and a DPoP key or mTLS thumbprint is also present.

The token endpoint enforces one-shot codes by removing the grant before checking anything, then checks expiry, client and redirect equality, S256, the PKCE verifier, and resource equality, and finally runs the same sender-constraint check with the code as the binding id. Codes live --auth-code-ttl-secs seconds (default 300) and the access tokens it signs live --auth-access-token-ttl-secs seconds (default 600). Token exchange accepts only an access token as the subject token type, verifies it was signed by this server’s own EdDSA key, requires the issuer to match, and refuses to widen scope beyond the subject token’s.

Guarantees and limits

Next Steps

• Session Lifecycle · the ledger, the lifecycle states, tombstones, and what a restored session must re-prove
• Node Overview · the rung this page sits on, and the five obligations a node hands a cluster
• Node State on Disk · the serving owner the admission sidecar claims, and the single-writer rule around it
• Backpressure & Limits · the per-IP limiter in full, and the other bounds this listener inherits
• Node Lifecycle · the drain deadline that bounds an open stream, and the hygiene defaults this edge keeps
• Health & Readiness · what a process answers about itself, next to what /admin/health reports here
• Core & Shell · what the per-session kernel refuses to do on its own