feat(local-mcp): cloud-run import wiring, composer UX, and relay design doc

Consolidates the rest of the local-MCP-to-cloud work into this PR:

- Cloud run creation payload gains imported_mcp_servers (behind the
  posthog-code-local-mcp-import flag): the user's importable local
  servers, in the shape the sandbox agent server's
  remoteMcpServerSchema accepts. Threaded TaskInput ->
  useTaskCreation -> prepareTaskInput -> TaskCreationSaga ->
  createTaskRun. The backend ignores the field until the Django half
  (specced in docs/cloud-mcp-import.md) lands.
- Cloud composer shows a LocalMcpServersButton listing local servers
  annotated "Available in cloud" / "Requires your machine" / "Not
  available in cloud".
- docs/cloud-mcp-import.md: Django-side spec (validation, secret
  storage, --mcpServers merge, codex reachability caveat) and header
  rotation design via the existing refresh_session command.
- docs/cloud-mcp-relay.md: Part 2 design (stdio + private-URL servers
  relayed to the desktop over the durable event stream, mirroring the
  question-relay pattern); implementation gated on review, behind
  posthog-code-mcp-relay.

Generated-By: PostHog Code
Task-Id: 7c87c3a4-0be6-475e-a8ec-269140ded301

Author: richardsolomou

docs/cloud-mcp-import.md

@@ -0,0 +1,171 @@
+# Importing local MCP servers into cloud task runs
+
+Status: client side implemented behind the `posthog-code-local-mcp-import`
+feature flag. The Django side (spec below) is not implemented; until it lands,
+the backend ignores the extra creation-payload field and cloud runs behave as
+before.
+
+## Problem
+
+A local task run gets all of the user's MCP servers: the PostHog MCP plus
+`MCPServerInstallation` records (built by `AgentAuthAdapter.buildMcpServers` in
+`packages/workspace-server/src/services/agent/auth-adapter.ts`), and — for the
+Claude adapter — the user's own servers from `~/.claude.json`
+(`loadUserClaudeJsonMcpServers` in
+`packages/agent/src/adapters/claude/session/mcp-config.ts`).
+
+A cloud run's sandbox only gets what the backend bakes into the agent server's
+`--mcpServers` flag at spawn (`remoteMcpServerSchema` in
+`packages/agent/src/server/schemas.ts`: `http`/`sse` + `url` + `headers`). The
+sandbox never reads `~/.claude.json`, so tasks that need the user's own MCP
+servers (Grafana, Sentry, internal tools, ...) force the user back to local
+runs.
+
+This document covers **import**: forwarding url-based servers that are
+reachable from the public internet. Servers that are not importable (stdio, or
+private-network URLs) need the desktop **relay** — see
+[cloud-mcp-relay.md](./cloud-mcp-relay.md).
+
+## What the client does
+
+1. **Read** — `LocalMcpService`
+   (`packages/workspace-server/src/services/local-mcp/local-mcp.ts`) reads
+   `~/.claude.json` through `loadUserClaudeJsonMcpServerEntries` (extracted
+   from the Claude adapter's loader so both share one parser) and normalizes
+   each entry to a `LocalMcpServerDescriptor` (`@posthog/shared`). stdio `env`
+   values are dropped at this boundary — they routinely hold secrets the
+   renderer has no use for.
+
+2. **Classify** — `LocalMcpImportService`
+   (`packages/core/src/local-mcp/localMcpImport.ts`) classifies each server:
+
+   | Server | Availability | Why |
+   | --- | --- | --- |
+   | `http`/`sse` with a public URL | `importable` | The sandbox can reach it directly. |
+   | `http`/`sse` on localhost, RFC1918, CGNAT (100.64/10, incl. Tailscale IPs), link-local, IPv6 ULA, `.local`/`.internal`/`.lan`/`.home`/`.home.arpa`/`.ts.net`, or a dotless intranet name | `requires_desktop` | Only reachable from the user's machine or network. |
+   | `stdio` | `requires_desktop` | A local process; nothing to forward. |
+   | Unparseable URL / non-http(s) scheme / unrecognized shape | `unsupported` | Can't run anywhere. |
+
+   The heuristic errs toward private: a public server misclassified as private
+   just stays desktop-only, while the reverse would ship an unreachable server
+   (or leak headers) to the sandbox.
+
+3. **Show** — the cloud task composer renders `LocalMcpServersButton`
+   (`packages/ui/src/features/task-detail/components/LocalMcpServersButton.tsx`),
+   a list of the user's servers annotated "Available in cloud" / "Requires
+   your machine" / "Not available in cloud".
+
+4. **Send** — importable servers are included in the run-creation payload
+   (`imported_mcp_servers` in `buildCloudRunRequestBody`,
+   `packages/api-client/src/posthog-client.ts`) in exactly the shape the agent
+   server's `remoteMcpServerSchema` accepts, so the backend can pass them
+   through to `--mcpServers` without transformation.
+
+Project-scoped (`projects[cwd].mcpServers`) entries are currently only picked
+up when a `cwd` is passed; cloud task creation selects a GitHub repository
+rather than a local checkout, so cloud runs import user-scoped servers only.
+Mapping repository → local checkout to include project-scoped servers is a
+follow-up.
+
+## Wire format
+
+`POST /api/projects/{project_id}/tasks/{task_id}/runs/` gains one optional
+field:
+
+```json
+{
+  "imported_mcp_servers": [
+    {
+      "type": "http",
+      "name": "grafana",
+      "url": "https://mcp.grafana.example.com/mcp",
+      "headers": [{ "name": "Authorization", "value": "Bearer ..." }]
+    }
+  ]
+}
+```
+
+`type` is `"http" | "sse"`. `headers` may be empty.
+
+## Django-side spec (not implemented in this repo)
+
+The `posthog/posthog` repo owns run creation and sandbox provisioning. To
+support the field:
+
+**Validation** (reject the run creation with 400 on violation):
+
+- ≤ 20 servers; `name` non-empty, ≤ 64 chars, unique within the list.
+- `url` must parse, scheme `http`/`https`, host must not be loopback /
+  RFC1918 / link-local / CGNAT / IPv6 ULA (re-validate server-side; the
+  client's classification is a UX aid, not a security boundary). This matters
+  because the sandbox egresses from PostHog infrastructure: a private URL
+  here is a user-controlled SSRF vector against whatever the sandbox network
+  can reach.
+- Each header value ≤ 4 KB; whole field ≤ 32 KB serialized.
+- Names must not collide with the reserved `posthog` server or with the names
+  of the project's `MCPServerInstallation`-derived servers; on collision the
+  imported server is dropped (installations win) and the run is still created.
+
+**Storage**: header values are credentials (`Authorization: Bearer ...`).
+Store them like other run secrets — encrypted at rest, write-only (never
+echoed back from the run detail API), and excluded from logs/analytics.
+
+**Spawn**: append the validated list to the `--mcpServers` array after the
+PostHog MCP and installation-derived servers. No other transformation — the
+payload shape is already `remoteMcpServerSchema`.
+
+**Adapter caveat**: codex-acp hard-fails on unreachable MCP servers, which is
+why the desktop prunes them for local Codex sessions
+(`filterReachableMcpServers` in
+`packages/workspace-server/src/services/agent/agent.ts`). The sandbox agent
+server does no such pruning. Either restrict `imported_mcp_servers` to
+`runtime_adapter == "claude"` initially, or add an equivalent reachability
+probe to the sandbox before session start for Codex runs.
+
+## Auth: header staleness and rotation
+
+Headers are captured at launch. For servers whose tokens expire mid-run, the
+rotation mechanism already exists on the sandbox side: the `refresh_session`
+command (`refreshSessionParamsSchema`,
+`packages/agent/src/server/schemas.ts`) pushes a fresh `mcpServers` list into
+a running session, and the Claude adapter tears down and rebuilds the query
+with the new list (`refreshSession` in
+`packages/agent/src/adapters/claude/claude-agent.ts`).
+
+What's missing is the client half — today the desktop never sends
+`refresh_session` for cloud runs (`sendCommandInput` in
+`packages/core/src/cloud-task/schemas.ts` stops at `set_config_option`).
+Design:
+
+1. Add `refresh_session` to the core cloud-task command schema and a
+   `CloudTaskService` method that posts it through the existing
+   `/runs/{run}/command/` endpoint with the full replacement `mcpServers`
+   list (the agent server treats the list as authoritative; an empty list is
+   a no-op by design, so "remove every imported server" cannot be expressed —
+   acceptable for rotation).
+2. Django: allow `refresh_session` through the command endpoint's method
+   allowlist, apply the same validation as `imported_mcp_servers`, forward
+   verbatim, and do not persist the params (they contain fresh credentials).
+3. Desktop trigger: re-read `~/.claude.json` when it changes (the
+   workspace-server already has file watchers) and push the updated list to
+   active cloud runs.
+
+**Why this ships as a documented follow-up rather than code**: static headers
+in `~/.claude.json` carry no expiry metadata, and OAuth-backed servers
+managed by Claude Code keep their tokens in Claude's credential store — not
+in `mcpServers.headers` — so those servers aren't importable this way at all
+(they surface as headerless imports that 401 in the sandbox; the relay in
+[cloud-mcp-relay.md](./cloud-mcp-relay.md) covers them properly). For the
+static-header servers we can import, there is nothing to watch except the
+file itself, which is the trigger described above.
+
+## Follow-ups
+
+- Codex local config (`~/.codex/config.toml` `mcp_servers`) as a second
+  source; needs a TOML parser, skipped for now.
+- Project-scoped `~/.claude.json` servers for cloud runs (repository → local
+  checkout mapping).
+- `${VAR}` environment-variable expansion in header values (Claude Code
+  expands these at session start; the import currently forwards them
+  literally, so such servers will 401 until expanded).
+- The `refresh_session` client path described above.