Remote-MCP 09: Stand up the authenticated remote MCP endpoint #938

New Issue

2026-07-26T00:34:00-05:00

jcwalker3 commented

2026-07-26 00:34:00 -05:00

Parent epic: #929.
Depends on: #933, #934, #935, #937.

Problem

Children 2 through 8 make the server capable of being remote: the transport bind is pluggable, the principal is per-request, credentials come from a provider, provenance and freshness have remote definitions, the tool boundary is enforced, and coordination state is safe under concurrency. None of that is reachable until something actually listens. This child is the first point at which a caller outside the operator's machine can connect, so it is also the first point at which the endpoint's own authentication and exposure become the trust boundary.

Scope

Deploy a running remote endpoint serving all five roles.

Select and configure the remote transport, using the seam from child 2.
Implement the endpoint handshake that authenticates a caller and issues the server-side session identity that child 5's provenance strategy demands.
Bind the authenticated caller to a principal, so the role a caller receives follows from the credential presented and cannot be selected by the caller at will.
Configure the credential provider from child 4 with the deployed secret store, so no keychain access is attempted.
Terminate transport security at or before the endpoint, and refuse unauthenticated and plaintext connections.
Apply per-session rate limiting and a bounded session lifetime, and expire idle sessions.
Emit structured operational logging and health output covering session establishment, refusals, and provenance verdicts, with no secret material.
Document deployment, configuration, credential rotation, and health checks in docs/remote-mcp/deployment.md.

Acceptance criteria

All five roles are reachable over the endpoint, each resolving its own principal.
A caller presenting one role's credential cannot obtain another role's permissions, proven by a negative test per role pair.
Unauthenticated and plaintext connection attempts are refused before any tool dispatch.
Mutations succeed only when the child 5 provenance strategy is satisfied, and the child 6 freshness gate reports mutation-safe.
Tools classified in child 7 as requiring the caller's filesystem are refused over this endpoint with the stated blocker.
No keychain access occurs on the host, proven by a test that fails if the keychain path is reached.
Session expiry, idle timeout, and rate limiting are enforced and covered by tests.
No log line, health output, or error message contains token or session-secret material.
docs/remote-mcp/deployment.md covers deployment, configuration, rotation, and health checks.

Verification

An end-to-end test establishes a session per role and exercises one read and one permitted mutation for each.
Negative tests cover: wrong-role credential, absent credential, expired session, plaintext attempt, and rate-limit breach.
A secret-redaction test spans logs, health output, tool results, and error messages.
Full suite compared against the recorded baseline, run from a branches/ worktree.

Non-goals

Decommissioning the local stdio fleet. Both run side by side until child 10 completes.
Multi-tenant hosting beyond this organization.
Moving the web console, which is tracked by issue #631.

Parent epic: #929. Depends on: #933, #934, #935, #937. ## Problem Children 2 through 8 make the server capable of being remote: the transport bind is pluggable, the principal is per-request, credentials come from a provider, provenance and freshness have remote definitions, the tool boundary is enforced, and coordination state is safe under concurrency. None of that is reachable until something actually listens. This child is the first point at which a caller outside the operator's machine can connect, so it is also the first point at which the endpoint's own authentication and exposure become the trust boundary. ## Scope Deploy a running remote endpoint serving all five roles. - Select and configure the remote transport, using the seam from child 2. - Implement the endpoint handshake that authenticates a caller and issues the server-side session identity that child 5's provenance strategy demands. - Bind the authenticated caller to a principal, so the role a caller receives follows from the credential presented and cannot be selected by the caller at will. - Configure the credential provider from child 4 with the deployed secret store, so no keychain access is attempted. - Terminate transport security at or before the endpoint, and refuse unauthenticated and plaintext connections. - Apply per-session rate limiting and a bounded session lifetime, and expire idle sessions. - Emit structured operational logging and health output covering session establishment, refusals, and provenance verdicts, with no secret material. - Document deployment, configuration, credential rotation, and health checks in `docs/remote-mcp/deployment.md`. ## Acceptance criteria - All five roles are reachable over the endpoint, each resolving its own principal. - A caller presenting one role's credential cannot obtain another role's permissions, proven by a negative test per role pair. - Unauthenticated and plaintext connection attempts are refused before any tool dispatch. - Mutations succeed only when the child 5 provenance strategy is satisfied, and the child 6 freshness gate reports mutation-safe. - Tools classified in child 7 as requiring the caller's filesystem are refused over this endpoint with the stated blocker. - No keychain access occurs on the host, proven by a test that fails if the keychain path is reached. - Session expiry, idle timeout, and rate limiting are enforced and covered by tests. - No log line, health output, or error message contains token or session-secret material. - `docs/remote-mcp/deployment.md` covers deployment, configuration, rotation, and health checks. ## Verification - An end-to-end test establishes a session per role and exercises one read and one permitted mutation for each. - Negative tests cover: wrong-role credential, absent credential, expired session, plaintext attempt, and rate-limit breach. - A secret-redaction test spans logs, health output, tool results, and error messages. - Full suite compared against the recorded baseline, run from a `branches/` worktree. ## Non-goals - Decommissioning the local stdio fleet. Both run side by side until child 10 completes. - Multi-tenant hosting beyond this organization. - Moving the web console, which is tracked by issue #631.