WebTTY over MCP

WebTTY can be operated through MCP when an agent needs to discover remote machines, run bounded commands, inspect managed sessions, or retrieve recordings. There are two MCP surfaces, and the preferred path is the local CLI MCP server.

rstream mcp serve runs on the operator machine. It can use the local rstream context, the private tunnel dialer, WebTTY known-server pins, WebTTY endpoint identities, trusted workspace devices, and local E2E grants. That makes it the right WebTTY surface for Codex desktop, Claude Code, local automation, encrypted sessions, filesystem sidecar access, and remote-local service exposure.

The hosted /api/mcp endpoint is a restricted Control plane surface. It is useful when an MCP client can call Streamable HTTP but cannot execute a local CLI process. It can still inventory WebTTY, manage registered server records, run bounded commands against non-E2E targets, read session metadata, export non-E2E recordings, and coordinate control requests. It never receives private E2E keys and never decrypts workspace-protected terminal data.

Surface split

This split keeps E2E simple to reason about. Hosted MCP can enforce policy and help agents operate the Control plane, but private WebTTY key material stays on trusted local clients.

Local MCP workflow

Register local MCP once:

rstream codex setup

The generated entry runs:

rstream mcp serve

After that, an agent can prepare the project context, list WebTTY servers, run a command, read session metadata, or export recordings through MCP tools. The local MCP server resolves WebTTY targets the same way the CLI does: local project context first, tunnel or registered-server resolution, local known-server trust, local endpoint identity, and workspace trusted-device material when the session is workspace-managed.

For E2E sessions, do not move keys into the prompt or hosted tools. Enroll the local device or configure explicit WebTTY identities locally, then let the local MCP server use that material.

Hosted MCP workflow

Hosted MCP uses Authorization: Bearer <token> and does not use browser cookies. Request only the permissions needed for the workflow.

For inventory and registered server management:

network.webtty-servers.read-only
network.webtty-servers.read-write
tunnels.resources.read-only

For non-E2E command execution:

account.projects.read-only
tunnels.resources.read-only
tunnels.streams.create-delete

For sessions, recordings, and control requests:

webtty.sessions.read-only
webtty.sessions.read-write
webtty.logs.read-only

Hosted WebTTY execution is intentionally bounded. The hosted tool resolves the target, refuses if the target requires E2E or client proof, creates a short-lived connect token scoped to that tunnel, executes one non-interactive command, caps output, and returns stdout, stderr, and exit code. If the target is E2E, the tool returns a local-trust error instead of dialing.

requires_local_trusted_mcp

That error means the agent must use rstream mcp serve on a trusted device. It is not a request to upload keys to hosted MCP.

Registered server records

Hosted MCP can create and update registered WebTTY server records because that is Control plane state. It does not start a remote server. Creation returns the server metadata and enrollment guidance so the runtime host can enroll and run the server through the CLI.

rstream webtty server enroll --project-id <project-id> --server-id <server-id> --enrollment-token <enrollment-token>
rstream webtty server -v --server-id <server-id>

The same rule applies to workspace-managed E2E. Hosted MCP can prepare the server record, but the trusted device and E2E runtime decisions happen through local browser or CLI trust flows, not through hosted private key handling.

Agent behavior

Agents should choose the surface by asking one question first: can this runtime execute the rstream CLI?

If yes, use local MCP for WebTTY. It is more capable, lower-friction for E2E, and closer to the runtime that owns local files and keys.

If no, use hosted MCP with the restricted feature set. The agent should be explicit when a requested WebTTY action requires local trust and should stop with a clear next step rather than attempting to bypass E2E through hosted APIs.

Related pages

Codex explains the workstation setup. Agent Native describes discovery and hosted MCP. CLI Workflow explains contexts and local MCP. End-to-End Encryption covers WebTTY trust and key material. Session Recordings covers encrypted recording export.