feat(mcp)!: v2.0.0 — Code Mode (workerd sidecar, 10-tool surface)

[pratikbin]

Summary

CreateOS MCP v2.0.0. Collapses 87 long-tail tool definitions into 3 code-mode tools backed by a workerd V8 sandbox sidecar, while keeping 7 native fast-path tools for hot operations.

Status: Draft. Blocked on autogen-backend-v2#451 (private) — see Cross-repo dependency below.
Rollout tracker: #12.

Tool surface (v2)

Native (7):  GetQuotas, GetSupportedProjectTypes, CheckProjectUniqueName,
             CreateProject, UploadDeploymentBase64Files, GetDeployment,
             CancelDeployment

Code Mode (3):
  search(code)    — read-only OpenAPI-spec introspection in a JS sandbox
  execute(code)   — typed CreateOS API calls in a JS sandbox
  pollJob(jobId)  — drain long-running execute() jobs

The full ~100-endpoint CreateOS API is reachable via execute. The model writes a single async arrow function that may chain multiple typed api.<group>.<operationId>(args) calls inside one sandbox boundary. Long-running ops (>90 s) auto-upgrade to a job; the model loops pollJob until done. Hard wall cap 600 s.

Token cost of the 10-tool descriptor surface: 896 tokens (gated at 1500).

Architecture

Two-process pod:

                ┌──────────────────────────────┐
   MCP client ──┤ mcp container (Go)           │
                │   - 7 native tools           │
                │   - 3 code-mode tools        │ ── HTTP /run /poll /health ──┐
                │   - /metrics /readyz         │                               │
                └──────────────────────────────┘                               │
                                                                              ▼
                                                     ┌─────────────────────────────────┐
                                                     │ workerd container (V8 sandbox)  │
                                                     │   dispatcher worker (:8787)      │
                                                     │     - spec bootstrap on boot    │
                                                     │     - dynamic worker loader     │
                                                     │       (one isolate per /run)    │
                                                     │   api-proxy worker               │
                                                     │     - only egress to backend    │
                                                     └─────────────────────────────────┘
                                                                              │
                                                                              ▼
                                                                       backend API

Comms strictly over loopback. The api-proxy worker is the only thing in the pod with backend egress.

Sandbox guarantees

• Each search/execute runs in a fresh V8 isolate spawned via the workerd Dynamic Worker Loader.
• No filesystem, no env vars, no ambient fetch. Only the host.js ESM module exposes spec, api, console, sleep.
• Auth headers (X-Api-Key, X-Access-Token for bearer) are forwarded by the dispatcher to api-proxy from the trusted MCP request context — user code cannot inject or override them.
• api.raw(method, path, opts) requires server-relative paths. Absolute URLs, protocol-relative //, and dot-segments (raw or percent-encoded) are rejected to prevent SSRF / BACKEND_URL prefix escape.
• Response headers are allowlisted; Set-Cookie and internal x-* headers are stripped before reaching user code.

Limits

search timeout	5 s
execute sync window	90 s
execute wall cap	600 s
Concurrent execute jobs	50 (429 beyond)
Concurrent search isolates	50
Job store size	500 (LRU evict on cap)
Job TTL after terminal	30 min
User code	1 MB
Result	64 KB (oversized truncated with __truncated)
sleep(ms) cap	60 s per call

Discovery surface (for clients)

• initialize.serverInfo.name → "CreateOS MCP (Code Mode v2)"
• tools/list → 10 tools; the 3 code-mode tools carry _meta = {mode:"code", sandbox:"workerd", version:"v2"}
• resources/list →
  • code-mode://intro (workflow + auth + sandbox + limits)
  • code-mode://api-shape (typed accessor + ApiError contract + discovery snippet)
• prompts/list →
  • code-mode/deploy-example (single execute that deploys + waits, with pollJob fallback)
  • code-mode/api-discovery (4 search snippets that walk from keyword to operationId)

Cross-repo dependency

This PR depends on autogen-backend-v2#451 (private repo). That PR adds a CI gate asserting every route in the OpenAPI spec carries an operationId. The MCP sidecar codegens its typed SDK from those operationIds.

Soft dependency — operations missing operationId fall through to api.raw(...), so v2 functions even before the backend PR merges. The hard requirement is for the typed surface to be complete in production. MCP v2 must not ship to prod until the backend PR is merged.

Backend ops tracker: NodeOps-app/autogen-backend-v2#452 (private).

Breaking changes

• 87 native MCP tools removed. Long-tail API surface is now reachable only via search/execute/pollJob.
• Server name in initialize.serverInfo.name changed from "MCP Server" to "CreateOS MCP (Code Mode v2)".
• Server version bumped to 2.0.0.

Native tools retained (7)

GetQuotas, GetSupportedProjectTypes, CheckProjectUniqueName, CreateProject, UploadDeploymentBase64Files, GetDeployment, CancelDeployment.

Operational

• New container: workerd sidecar built from codemode/workerd/Dockerfile (oven/bun base, non-root user, --experimental workerd flag for the Dynamic Worker Loader).
• k8s/pod-v2.yaml — two-container pod manifest. MCP container reads config from CREATEOS_MCP_CONFIG env (mounted ConfigMap at /etc/createos).
• mcp /readyz — 200 only when workerd /health responds 200.
• mcp /metrics — Prom: codemode_run_duration_seconds{mode,outcome}, codemode_jobs_running, codemode_jobstore_size, codemode_api_call_duration_seconds.
• WORKERD_URL env (default http://127.0.0.1:8787) tells the MCP binary where the sidecar lives.

CI

• .github/workflows/token-budget.yml — bun scripts/count-tokens.ts asserts the 10-tool descriptor surface stays ≤1500 tokens (currently 896).

Test plan

• go build ./... clean
• go test ./codemode/... passes (15 unit tests)
• bun test in codemode/workerd/ passes (28 tests across dispatcher, spec-loader, host, api-proxy, api-sdk-builder)
• CODEMODE_INTEGRATION=1 go test -tags integration passes (3 end-to-end tests, real workerd subprocess, mock backend)
• bun scripts/count-tokens.ts — 896/1500
• Manual smoke: search returns spec paths, execute calls real backend with caller auth, pollJob returns terminal envelopes, /readyz reflects workerd /health, /metrics reachable
• Staging deploy via k8s/pod-v2.yaml
• 1-week internal team soak on staging
• Blue-green canary to prod (5% → 25% → 50% → 100%)

Files

• codemode/ — Go pkg (client, handler, auth, health, metrics, discovery)
• codemode/workerd/ — workerd config (Cap'n Proto), dispatcher.js, host.js, api-proxy.js, api-sdk-builder.js, spec-loader.js, Dockerfile, bun tests
• server.go — registers 7 native + 3 code-mode tools + 2 resources + 2 prompts
• main.go — workerd health probe, /readyz, /metrics, codemode auth-header middleware
• Dockerfile — distroless/static, nonroot
• k8s/pod-v2.yaml — pod manifest
• scripts/{count-tokens,smoke,soak}.ts — CI gate + load tests
• README.md — Code Mode section + 10-tool surface