@terreno/mcp 57.16.2 → 57.18.0

package/dist/docs/versioned/57.17.0/implementationPlans/infra-mcp-research.md

@@ -0,0 +1,189 @@
+# Research: Infrastructure MCP server (privileged tools gateway)
+
+**Status:** Complete — decisions made, IP written: [infra-mcp.md](infra-mcp.md)
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1090
+**Created:** 2026-08-09
+
+## Scope statement
+
+Evaluate approaches for a new deployable, self-contained MCP server ("infra MCP") that puts privileged infrastructure tooling — GCP, Expo/EAS, Vercel, MongoDB, Sentry, and similar — behind a single MCP endpoint that:
+
+- Authenticates each user individually.
+- Enforces per-user permissions (at minimum: read-only vs. write tiers; e.g. "log digging" vs. "change infra").
+- Is deployable as its own service (Cloud Run, following the existing `terreno-mcp` deployment pattern).
+
+Also: confirm whether targeting the new MCP spec revision ("MCP 2.0") is the right call.
+
+## PRD summary
+
+From the request:
+
+- **Problem:** Privileged infra tools are currently accessed with broadly-scoped credentials (e.g. env-injected service accounts, personal API keys). There is no per-user gate, no read-only tier, and no central audit point for agent-driven infra access.
+- **Goal:** One MCP server controlling authentication and authorization per user, supporting a read-only mode (log digging, metrics, build status) and a write mode (actual infra changes).
+- **Integrations named:** GCP, Expo/EAS, Vercel, MongoDB, Sentry, "etc." (extensible).
+- **Constraint:** Deployable and self-contained.
+
+## Codebase findings
+
+### Existing MCP package (`mcp-server/`)
+
+- `@terreno/mcp` is a docs/codegen MCP server on `@modelcontextprotocol/sdk` **v1.27** (2025-era spec), served over Streamable HTTP via `createMcpExpressApp` + `StreamableHTTPServerTransport`, wrapped with Sentry (`Sentry.wrapMcpServerWithSentry`).
+- It has **no authentication** — it serves public docs/tooling. It is not a suitable base for privileged tools but proves out the HTTP-MCP + Sentry + Cloud Run shape.
+- A second bin (`terreno-mcp-local`) runs stdio-side local tools (logs, db query/schema, runtime) — relevant prior art for "log digging" tool design.
+
+### Deployment prior art (`terraform/`)
+
+- `module "mcp_service"` deploys `terreno-mcp` to **Cloud Run** with its own Artifact Registry repo, min/max instances, and a scoped deploy service account. A new infra MCP service can clone this module usage nearly verbatim.
+
+### Auth/permissions prior art (`api/`)
+
+- `@terreno/api` ships JWT/Passport auth, Better Auth (OAuth 2.x social login), a permission system (`IsAdmin`, `IsAuthenticated`, per-route permission arrays), and the `TerrenoPlugin` pattern.
+- The [RBAC Permissions IP](rbac-permissions.md) (Draft) is designing richer role-based permissions for `@terreno/api` — potential overlap if the infra MCP models roles in Mongo.
+
+### Related IPs
+
+- [modelRouter MCP tools](model-router-mcp.md) (backlog): generates MCP tools from modelRouter with per-tool auth — same "authenticated MCP tools" problem, app-data-facing rather than infra-facing.
+- [MCP Boost parity](mcp-boost-parity.md) (in progress, PR #802): expands `@terreno/mcp`.
+- [Deploy to GCP](deploy-to-gcp.md), [Deployment foundation](deployment-foundation.md): deployment story this service should align with.
+
+### Current credential handling (the problem being solved)
+
+- Cloud agent VMs receive raw env-injected service accounts (`GCP_SA_TERRENO`, `GCP_SA_PRD`, `GCP_SA_STG`, `GCP_SA_ZAPLING`) and `SENTRY_CLIENT_SECRET`. Every agent gets the full power of each credential; scoping is done only at the GCP IAM level per SA, with no read-only/write split per user and no central audit trail.
+
+## External findings
+
+### "MCP 2.0" — the 2026-07-28 spec revision
+
+There is no product officially named "MCP 2.0", but the **2026-07-28 MCP specification** is the largest revision since launch and is what the TypeScript **SDK v2** implements. Its changes are unusually well-suited to this project:
+
+- **Stateless core** — the `initialize` handshake and `Mcp-Session-Id` are gone; every request is self-contained. Scales on plain HTTP load-balanced infra (ideal for Cloud Run).
+- **Header-based routing** — `Mcp-Method` and `Mcp-Name` HTTP headers are mandatory and mirrored to the body (mismatch → `-32020`). A gateway or middleware can authorize per-tool **from headers alone**, without parsing JSON-RPC bodies. This is effectively purpose-built for the per-user, per-tool permission layer this project needs.
+- **Authorization hardening** — OAuth 2.1 + PKCE, RFC 9728 Protected Resource Metadata (401 + `WWW-Authenticate` discovery), RFC 8707 resource indicators (anti-confused-deputy), RFC 9207 issuer validation, and Client ID Metadata Documents (CIMD) replacing Dynamic Client Registration.
+- **Tasks extension** — long-running work (e.g. an EAS build or terraform apply) has a first-class pattern.
+
+SDK situation:
+
+- TS SDK v2 = new packages `@modelcontextprotocol/server` (+ `@modelcontextprotocol/client`, `@modelcontextprotocol/node`), released stable 2026-07-28. The v1 `@modelcontextprotocol/sdk` line (which `@terreno/mcp` uses) remains maintained; both can coexist in one repo.
+- `createMcpHandler(factory, {legacy: "stateless"})` serves **both** 2026-era and 2025-era clients from one endpoint, so older MCP clients (Claude Code/Cursor versions that predate the spec) still work.
+- Gotcha: SDK v2 requires a Standard Schema validator with a `jsonSchema` property — **zod 4** (repo catalog currently needs checking; may need `zod@^4` under an alias if anything pins zod 3).
+
+**Conclusion: yes — build new on the 2026-07-28 spec via SDK v2 with the legacy stateless fallback.** Starting a new privileged server on the 2025-era SDK would mean migrating within months and would forfeit the header-based authz and stateless scaling that this project specifically benefits from.
+
+### Vendor MCP server landscape (all targets have official servers)
+
+| Vendor | Official MCP server | Auth model | Notes |
+|---|---|---|---|
+| GCP | Managed remote endpoints (e.g. `https://cloudcli.googleapis.com/mcp` for gcloud, plus BigQuery/Storage/etc.); open-source `gcloud-mcp`, `observability-mcp`, `storage-mcp` (npm, runnable self-hosted) | OAuth 2.0 + IAM | Remote server blocks `gcloud auth`, `gcloud iam service-accounts`, etc. Observability MCP covers logs/metrics/traces/errors — the "log digging" use case |
+| Sentry | Hosted `https://mcp.sentry.dev/mcp` and self-hostable | OAuth | Issues, events, traces, Seer |
+| MongoDB | `mongodb-mcp-server` (official, npm) | Connection string / Atlas API creds | Has a `--readOnly` flag — native read-only mode |
+| Vercel | Hosted `https://mcp.vercel.com` | OAuth | Deployments, logs, projects |
+| Expo/EAS | Hosted `https://mcp.expo.dev/mcp` (Streamable HTTP) | OAuth (Expo account); paid EAS plan | Docs + project tools; EAS build/update tools evolving |
+
+### Proxying feasibility per vendor (follow-up research)
+
+Mechanics of chaining our MCP to upstream MCP servers are simple with SDK v2 (`@modelcontextprotocol/client` speaks both protocol eras; stateless spec = no per-upstream session to maintain; stdio servers run as child processes). Long-term authentication is the real differentiator:
+
+| Vendor | Headless credential for MCP? | Long-term auth | Verdict for proxying |
+|---|---|---|---|
+| Sentry | Yes — hosted `mcp.sentry.dev` accepts `Authorization: Sentry-Bearer <token>` header; stdio `@sentry/mcp-server` takes `SENTRY_ACCESS_TOKEN` (non-expiring user auth token / internal integration token) | Static token, rotate manually | **Green** |
+| MongoDB | Yes — `mongodb-mcp-server` takes a connection string; native `--readOnly` flag | Static | **Green** |
+| GCP | Yes — remote endpoints and self-hosted `gcloud-mcp`/`observability-mcp` accept ADC/service-account identity; on Cloud Run the *service's own SA* is the credential, google-auth auto-refreshes | Automatic (workload identity) | **Green** |
+| Vercel | **No** — `mcp.vercel.com` is OAuth-only **with a client allowlist** (Claude, Cursor, Codex, etc.); our server would not be an approved client, and there is no API-token fallback | n/a | **Red** — go native (Vercel REST API + static token) |
+| Expo/EAS | Hosted `mcp.expo.dev` is browser OAuth (user-scoped, paid plan); robot tokens (`EXPO_TOKEN`) are for CI/CLI, MCP acceptance unconfirmed | Uncertain | **Amber/Red** — go native (`EXPO_TOKEN` + EAS CLI/GraphQL) |
+
+Implication: a **pure** gateway (Option A) is not achievable for Vercel and likely not Expo — their hosted MCPs are designed for interactive human OAuth from allowlisted AI clients, not server-to-server delegation. The proxied path works cleanly exactly where static/service credentials exist, which is the same place the native path is also easy. This strengthens Option C (hybrid) and weakens A.
+
+If we ever must proxy an interactive-OAuth-only upstream: one-time browser consent by an admin, persist the refresh token in an encrypted vault (Mongo + KMS or Secret Manager), background refresh, and an admin "re-link integration" flow for `invalid_grant`/revocation. Real ops burden — avoid unless the vendor MCP offers something the REST API doesn't.
+
+### Gateway prior art
+
+Multiple open-source projects already implement "aggregate MCP backends + per-user tool RBAC":
+
+- `mcp-zero-trust-proxy` — OAuth 2.1 front door (any OIDC provider), roles with `allowed_tools`/`deny_tools`, claim-based role mapping, audit logging, rate limiting. Config-file driven.
+- `joshrotenberg/mcp-proxy` (Rust) — multi-backend aggregation, capability filtering per backend, JWT/JWKS RBAC, token passthrough, OTel.
+- Microsoft `mcp-gateway` — Kubernetes-native, session-aware routing, Entra ID.
+- Common pattern: filter `tools/list` by role, deny `tools/call` for unauthorized tools, route by prefix to upstream servers.
+
+These validate the architecture but none is a drop-in: they are config-file-driven (not Mongo-backed per-user), most predate the 2026-07-28 stateless spec, and none handles the "server holds privileged vendor credentials per role tier" model out of the box.
+
+## Candidate options
+
+Two orthogonal decisions: **(1) where tools come from** and **(2) whose credentials execute them**. Options A–C cover decision 1; the credential question is listed separately because it applies to all three.
+
+### Option A: Pure gateway/aggregator over vendor MCP servers
+
+New service speaks MCP to clients, authenticates users itself (OAuth 2.1 per the new spec), and proxies tool calls to upstream vendor MCP servers (GCP remote MCP, Sentry, Vercel, Expo hosted; MongoDB MCP as an in-process/sidecar child). Per-user roles filter which upstream tools appear in `tools/list` and which pass `tools/call`.
+
+- **Pros:** Least tool-maintenance — vendors maintain their own tools; broad coverage immediately; new-spec `Mcp-Name` headers make the filter layer thin; read-only tiers are mostly "allow-list of known-read tools" plus MongoDB's native `--readOnly`.
+- **Cons:** Upstream hosted servers (Expo, Vercel, Sentry, GCP remote) authenticate via *their own* OAuth — the gateway must hold/refresh upstream tokens (per user, or one service identity), which is real complexity (token vault); read/write classification of third-party tools is inference, not contract — a mislabeled vendor tool could let a "read-only" user mutate infra; tool churn upstream can silently change the permission surface; latency of double-hop.
+
+### Option B: Self-contained curated tool server (no upstreams)
+
+Hand-write a curated set of tools that call vendor APIs/SDKs directly (Cloud Logging API, Sentry REST API, Vercel API, EAS GraphQL/CLI, MongoDB driver). The server holds vendor credentials (e.g. two GCP SAs: viewer + editor; a read-only Mongo user + a write user). Every tool is explicitly classified read or write at authorship time.
+
+- **Pros:** Read-only is a *hard guarantee* — enforced twice (tool tier + underlying credential scope, e.g. viewer-only SA for the read tier); smallest attack surface; no upstream token management; full control over tool descriptions/outputs (can redact); simplest to audit.
+- **Cons:** Highest build-and-maintain cost — every vendor surface is our code; coverage starts narrow (whatever tools we write); vendors ship new capabilities that we lag behind.
+
+### Option C: Hybrid — curated core + optional proxied upstreams (adapter model)
+
+Same authenticated core as B, with an integration-adapter interface. Each integration is either **native** (hand-written tools calling vendor APIs, like B) or **proxied** (an MCP client to an upstream server with an explicit per-tool allow-list and read/write annotation required in config, like A). Start native for the high-risk/high-value surfaces (GCP logs + deploys, Mongo, Sentry), add proxied adapters where a vendor MCP is high-quality and low-risk.
+
+- **Pros:** Ships useful read-only value fast on the native path; keeps the hard read-only guarantee where it matters; leaves a sanctioned escape hatch to vendor servers without weakening the permission model (proxied tools are deny-by-default until annotated); the 2026-07-28 header routing makes both paths share one authz middleware.
+- **Cons:** Two code paths to test; the proxied path inherits A's token-management complexity *when used*; discipline required so the allow-list doesn't rot into "allow everything".
+
+### Cross-cutting: credential model (applies to A/B/C)
+
+1. **Server-held, role-tiered service credentials** — users authenticate to the infra MCP; tool calls execute with shared per-tier credentials (e.g. `infra-mcp-readonly@` SA vs `infra-mcp-editor@` SA). Simple, strong read-only floor, but vendor-side audit logs show the service identity, not the human (the MCP server's own audit log must carry user attribution).
+2. **Per-user upstream identity (on-behalf-of)** — each user links their own GCP/Sentry/Vercel/Expo account via OAuth; the server stores/refreshes their tokens and acts as them. Vendor audit logs show the real human; but requires a token vault, per-vendor OAuth apps, and users must all have vendor accounts with correct IAM — significantly more work.
+3. **Hybrid** — server-held credentials for read tier (low risk, frictionless), per-user identity required for write tier.
+
+### Cross-cutting: where the code lives
+
+- **New workspace package in terreno** (e.g. `infra-mcp/`), reusing `@terreno/api` (Mongo user model, logger, Sentry patterns) and cloning the `mcp_service` terraform module — fits monorepo conventions, and `@terreno/api`'s auth/permission machinery is available.
+- **Standalone generic product package** (e.g. `@terreno/infra-mcp` designed for any org to deploy, config-driven integrations) — bigger ambition, aligns with the OSS launch program, more design constraints up front.
+
+## Audience fit (one-man shop → startup → growing startup)
+
+The target audience for the packaged product is solo founders through growing startups (not identity-team enterprises). That constraint selects the architecture:
+
+- **Credential model 1 (server-held, role-tiered)** is the only model that works at the low end: paste tokens once, nothing expires (static tokens + workload identity), no per-vendor OAuth app registration. Vendor-side audit logs show the service identity, so the product's own Mongo audit log (with user attribution) is the compliance answer at this scale.
+- **Better Auth logins (GitHub/Google/email)** instead of requiring an external IdP — the audience has GitHub accounts, not Okta. Domain-restricted Google login covers the "growing startup" tier.
+- **CTO security story is structural, not procedural:** read tier executes with physically read-only credentials (viewer SA, read-only Mongo user) so misclassified tools cannot mutate; proxied tools deny-by-default until annotated; per-integration grants; full audit log. `admin-backend`/`admin-frontend` provide the user/role admin UI.
+- **Enterprise upgrade path preserved:** credential resolution takes a user context, so a future "write tier requires linking your own vendor identity" mode (model 3) can be added without rearchitecting.
+- **Packaging:** reusable `@terreno/infra-mcp` package with config-driven integration registry, dogfooded via our own Cloud Run deployment — aligns with the OSS launch program.
+
+This resolves blocking questions 1 (Option C), 2 (model 1 with model-3 upgrade path), 3 (Mongo users via Better Auth), 4 (readonly/write tiers + per-integration grants), and 8 (reusable package).
+
+## Recommendation (pending answers)
+
+Option **C** (hybrid, starting native-first per B) with credential model **1** (server-held role-tiered credentials) as the initial phase, built as a new terreno workspace package on the 2026-07-28 spec via TS SDK v2, deployed to Cloud Run alongside `terreno-mcp`. But this is presented as a recommendation, not a decision — see blocking questions.
+
+## Blocking questions
+
+1. **Tool sourcing:** Option A (proxy vendor MCPs), B (all curated/native), or C (hybrid, native-first)?
+2. **Credential model:** server-held tiered credentials, per-user vendor identity, or hybrid (read=shared, write=per-user)?
+3. **User store & login:** Mongo-backed users in this service (reusing `@terreno/api` auth / Better Auth as the OAuth 2.1 authorization server), or an external IdP (Google Workspace / GitHub org) with the MCP server as a pure resource server? Who administers users/roles, and via what surface (admin UI? config? CLI)?
+4. **Permission granularity for v1:** just two tiers (readonly/write) per user, or per-integration grants (e.g. "Sentry read + Mongo read, no GCP")?
+5. **Write-action safety:** should write tools require an extra confirmation step (MCP elicitation), a second approval, or is role membership sufficient?
+6. **Integration priority for phase 1:** which 2–3 integrations first? (Research suggests GCP logs/observability + Sentry + Mongo read-only covers the "log digging" case.)
+7. **Audit requirements:** is an in-Mongo audit log of every tool call (user, tool, args, result status) a v1 requirement?
+8. **Packaging ambition:** terreno-internal service first, or design from day one as a reusable OSS-able `@terreno/*` package (affects config surface and scope)?
+9. **Consumers:** which MCP clients must work day one (Cursor cloud agents, Claude Code, humans' IDEs)? Cloud agents matter because they currently get raw SA env vars — is replacing those env-injected SAs an explicit goal?
+
+## Non-blocking questions
+
+- Rate limiting per user/tier in v1 or deferred?
+- Should the existing `@terreno/mcp` docs server eventually merge into or share infra with this service, or stay separate? (Default: separate.)
+- Naming: `infra-mcp`, `@terreno/infra-mcp`, `terreno-ops-mcp`?
+
+## References
+
+- MCP 2026-07-28 spec: https://modelcontextprotocol.io/specification/2026-07-28
+- Spec release notes: https://blog.modelcontextprotocol.io/posts/2026-07-28/
+- TS SDK v2 (`@modelcontextprotocol/server`): https://ts.sdk.modelcontextprotocol.io/v2/
+- SDK v2 legacy support guide: https://ts.sdk.modelcontextprotocol.io/v2/migration/support-2026-07-28
+- MCP authorization tutorial (OAuth 2.1): https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/authorization
+- GCP MCP servers: https://github.com/googleapis/gcloud-mcp, https://docs.cloud.google.com/sdk/use-gcloud-mcp, https://github.com/Google/mcp
+- Expo MCP: https://docs.expo.dev/eas/ai/mcp/
+- Gateway prior art: https://github.com/keith-aykira/mcp-zero-trust-proxy, https://github.com/joshrotenberg/mcp-proxy, https://microsoft.github.io/mcp-gateway/
+- In-repo: `mcp-server/src/index.ts`, `terraform/main.tf` (`mcp_service`), `docs/implementationPlans/model-router-mcp.md`, `docs/implementationPlans/rbac-permissions.md`

package/dist/docs/versioned/57.17.0/implementationPlans/infra-mcp.md

@@ -0,0 +1,269 @@
+# Implementation Plan: Infrastructure MCP server (`@terreno/infra-mcp`)
+
+**Status:** Approved — unblocked; RBAC module is Complete ([rbac-permissions.md](rbac-permissions.md))
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1090
+**Branch:** TBD
+**Owner:** TBD
+**Created:** 2026-08-09
+**Research:** [infra-mcp-research.md](infra-mcp-research.md)
+
+## Goal
+
+A deployable, self-contained MCP server that puts privileged infrastructure tooling — GCP, Sentry, MongoDB, and later Expo/EAS and Vercel — behind a single MCP endpoint with per-user authentication, RBAC-driven read/write permission tiers, per-call write confirmation, and a full audit trail. Packaged as a reusable `@terreno/infra-mcp` workspace package targeting one-man shops through growing startups, dogfooded by our own Cloud Run deployment. Cloud agents stop receiving raw `GCP_SA_*` service-account env vars and instead call this server with scoped service tokens.
+
+## Non-Goals
+
+- Per-user vendor identity (on-behalf-of OAuth to GCP/Sentry/etc.) — the credential interface accepts a user context so this can be added later, but v1 executes with server-held credentials.
+- Proxying vendor MCP servers that require interactive browser OAuth (Vercel `mcp.vercel.com`, Expo `mcp.expo.dev`) — research showed these are allowlisted/interactive-only; those vendors get native tools instead.
+- A bespoke permission engine — permissioning is the `@terreno/api` RBAC module (`createAccess`), not custom code.
+- Rate limiting, cost tracking, tool versioning (future work).
+- Changes to the existing `@terreno/mcp` docs server (stays on SDK v1, unchanged).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Approach | **Option C (hybrid):** native curated tools first; proxied vendor-MCP adapters behind an explicit per-tool allow-list with mandatory read/write annotation |
+| Protocol | **MCP 2026-07-28 spec** via TS SDK v2 (`@modelcontextprotocol/server`), `createMcpHandler` with `legacy: "stateless"` so 2025-era clients keep working |
+| Permissioning | **`@terreno/api` RBAC module** — this IP is blocked behind that PR. Each integration is an RBAC resource with `read`/`write` actions; meta-permissions live on an `infra` resource |
+| Write safety | **Write tools require per-call confirmation (MCP elicitation).** A config option can disable confirmation per integration or globally, but it only takes effect for users holding `infra:writeUnconfirmed` — everyone else is still prompted |
+| Phase 1 scope | **Read-only:** GCP observability (logs/metrics/errors), Sentry, MongoDB |
+| GCP credentials | **Cloud Run default runtime service account only (ADC).** No injected SA key env vars anywhere; the `GCP_SA_*` pattern for cloud agents is retired. IAM on the runtime SA is the outer bound; the MCP's RBAC is the per-user gate |
+| Other credentials | Static tokens (Sentry auth token, Mongo connection strings, later `EXPO_TOKEN`/Vercel token) from Secret Manager/env |
+| User store & login | Mongo users via `@terreno/api` (`baseUserPlugin` + `rbacUserPlugin`); MCP clients authenticate via OAuth 2.1 using **`@better-auth/oauth-provider` + `@better-auth/mcp`** (already aligned with the 2026-07-28 authorization spec: CIMD, RFC 9728, `requireMcpAuth`) |
+| Non-human callers | Service tokens (Better Auth `apiKey` plugin if compatible, else a `ServiceToken` model) mapped to machine users with RBAC roles — this is how cloud agents call the server |
+| Packaging | New workspace package `infra-mcp/` publishing `@terreno/infra-mcp`; config-driven integration registry; deployed via a clone of the existing `mcp_service` terraform module |
+
+## Architecture
+
+```
+MCP client (Cursor, Claude Code, cloud agent)
+  | OAuth 2.1 bearer token (human) or service token (machine)
+  v
+POST /mcp  — SDK v2 createMcpHandler (2026-07-28 + legacy stateless)
+  |
+  1. Auth: Better Auth verifies token -> User (+ roles via rbacUserPlugin)
+  2. Authz: access.can({[integration]: [tier]}) using Mcp-Name header ->
+     integration/tool lookup; tools/list is filtered to the caller's grants
+  3. Write tools: elicitation confirmation (unless override + infra:writeUnconfirmed)
+  4. Dispatch: IntegrationAdapter (native handler | proxied MCP client)
+  5. Audit: InfraAuditLog record for every tools/call
+```
+
+### Integration adapter interface
+
+```typescript
+// infra-mcp/src/integrations/types.ts
+export interface InfraToolContext {
+  user: UserDocument;            // resolved caller (human or machine)
+  access: TerrenoAccess<InfraStatements>;
+  confirmWrite: (summary: string) => Promise<boolean>; // elicitation wrapper
+  logger: Logger;
+}
+
+export interface InfraTool {
+  name: string;                  // exposed as `${integration}_${name}`
+  tier: "read" | "write";       // maps to the RBAC action checked
+  description: string;
+  inputSchema: ZodType;          // zod 4 (SDK v2 Standard Schema requirement)
+  handler: (args: unknown, ctx: InfraToolContext) => Promise<ToolResult>;
+}
+
+export type IntegrationAdapter =
+  | {kind: "native"; name: string; tools: InfraTool[]}
+  | {
+      kind: "proxied";
+      name: string;
+      transport: {type: "stdio"; command: string[]} | {type: "http"; url: string; headers?: Record<string, string>};
+      // Deny-by-default: only listed upstream tools are exposed, and each
+      // MUST carry an explicit tier annotation.
+      allowedTools: Record<string, {tier: "read" | "write"; rename?: string}>;
+    };
+```
+
+Proxied adapters use `@modelcontextprotocol/client` (speaks both protocol eras; stateless — no per-upstream session). Stdio upstreams run as child processes inside the container.
+
+### RBAC statements
+
+```typescript
+// infra-mcp/src/access.ts — merged with terrenoStatements via createAccess
+export const infraStatements = {
+  ...terrenoStatements,
+  gcp: ["read", "write"],
+  sentry: ["read", "write"],
+  mongo: ["read", "write"],
+  expo: ["read", "write"],      // phase 3
+  vercel: ["read", "write"],    // phase 3
+  infra: ["viewAudit", "manageIntegrations", "writeUnconfirmed"],
+} as const;
+```
+
+- `read`/`write` are in the RBAC module's `READ_ACTIONS` semantics, so the shipped `auditor` role (read-only everywhere) works unmodified — that is the "log digging" role for free.
+- Default roles seeded on top of the RBAC defaults: `infra-readonly` (every integration `read`), `infra-operator` (`read` + `write`, still confirmed per call), `superadmin` from RBAC covers everything including `infra:writeUnconfirmed`.
+- Per-integration grants ("Sentry read only, no GCP") are just roles with narrower permission sets — no extra machinery.
+
+### Write confirmation flow
+
+1. Tool handler for a `write`-tier tool calls `ctx.confirmWrite(summary)` before mutating.
+2. `confirmWrite` sends an MCP **elicitation** request to the client ("Confirm: roll back Cloud Run service X to revision Y? yes/no") and resolves with the user's answer. Decline → tool returns a cancelled result; audit records `rejected`.
+3. Override: `config.integrations[name].confirmWrites: false` (or global `confirmWrites`) skips the elicitation **only when** `access.can({infra: ["writeUnconfirmed"]})` passes for the caller. Without the permission, the config flag is ignored and the prompt still fires.
+4. Clients that do not support elicitation (some non-interactive agents): write tools **fail closed** with an instructive error unless the caller holds `infra:writeUnconfirmed` and the override is on.
+
+### Configuration
+
+Static config (code/env, validated at boot with zod):
+
+```typescript
+// consuming app / our deployment: infra.config.ts
+export default defineInfraMcp({
+  integrations: {
+    gcp: {enabled: true, projectId: env("GCP_PROJECT")},           // ADC — no key
+    sentry: {enabled: true, authToken: secret("SENTRY_MCP_TOKEN"), org: "flourish"},
+    mongo: {enabled: true, readUri: secret("MONGO_READ_URI"), writeUri: secret("MONGO_WRITE_URI")},
+  },
+  confirmWrites: true, // global default; per-integration override allowed
+});
+```
+
+## Models
+
+All models live in `infra-mcp/src/types/models/` per convention; every field carries a `description`.
+
+### User
+
+`@terreno/api` user schema with `baseUserPlugin` + `rbacUserPlugin` (adds `roles: string[]`). Machine users (cloud agents) are ordinary users flagged `isServiceAccount: true`.
+
+### InfraAuditLog
+
+| Field | Type | Notes |
+|---|---|---|
+| `userId` | ObjectId ref User | caller (human or machine) |
+| `tool` | string | full exposed tool name |
+| `integration` | string | adapter name |
+| `tier` | "read" \| "write" | |
+| `args` | Mixed | redacted via per-tool redaction list before persist |
+| `status` | enum | `allowed`, `denied`, `confirmed`, `rejected`, `error` |
+| `error` | string? | |
+| `durationMs` | number | |
+| `created` | Date | plugin-managed |
+
+Indexed on `{userId, created}` and `{integration, created}`. Read surface gated by `infra:viewAudit`.
+
+### ServiceToken (only if Better Auth `apiKey` plugin is unsuitable)
+
+`name`, `hashedToken`, `userId`, `expiresAt?`, `lastUsedAt`, `created`. Verified in the same auth middleware path as bearer tokens.
+
+## APIs
+
+| Method | Path | Auth | Purpose |
+|---|---|---|---|
+| POST | `/mcp` | OAuth bearer / service token | MCP endpoint (2026-07-28 + legacy stateless) |
+| GET | `/.well-known/oauth-protected-resource` | — | RFC 9728 metadata (via `@better-auth/mcp`) |
+| * | `/oauth2/*`, `/api/auth/*` | — | Better Auth authorization server + login pages |
+| GET | `/health` | — | health check |
+| * | `/rbac/*` | RBAC perms | role CRUD/assignment (RBAC module's `rbacRouter`) |
+| * | `/admin/*` | `admin:access` | admin panel (`@terreno/admin-backend`): Users, InfraAuditLog (read-only), ServiceTokens |
+
+### Phase 1 tools (read tier)
+
+| Integration | Tools |
+|---|---|
+| gcp | `gcp_query_logs`, `gcp_list_log_names`, `gcp_query_metrics`, `gcp_list_error_groups`, `gcp_list_cloud_run_services`, `gcp_get_cloud_run_service` |
+| sentry | `sentry_search_issues`, `sentry_get_issue`, `sentry_list_issue_events`, `sentry_get_event` |
+| mongo | `mongo_list_collections`, `mongo_collection_schema`, `mongo_find`, `mongo_aggregate` (read-only stages; `$out`/`$merge` rejected; executed on the read-only connection) |
+
+GCP tools call the Cloud Logging/Monitoring/Error Reporting/Cloud Run Admin APIs via ADC. Sentry tools call the Sentry REST API. Mongo tools reuse the read-query/schema logic behind `mcp-server/src/local/tools/databaseQuery.ts`/`databaseSchema.ts` — extracted into a shared module both packages import rather than forked into infra-mcp — run against the configured read URI.
+
+### Phase 2 tools (write tier, all elicitation-confirmed)
+
+Initial minimal set: `sentry_resolve_issue`, `sentry_assign_issue`, `gcp_rollback_cloud_run_revision`, `gcp_update_cloud_run_traffic`, `mongo_update_one`, `mongo_delete_one` (write URI). Expansion is deliberate and per-PR.
+
+## Notifications
+
+None in v1. Future: optional Slack notifier (via `@terreno/api` notifiers) on write-tier tool execution.
+
+## UI
+
+No new frontend package. Admin surfaces reuse `@terreno/admin-backend` + `@terreno/admin-frontend`/`admin-spa`:
+
+- Users + role assignment (RBAC module's admin screens per its IP).
+- InfraAuditLog read-only table (`listFields`: created, user, tool, tier, status).
+- ServiceToken management (create shows the token once).
+
+## Phases
+
+### Phase 1 — Read-only core (the "log digging" MVP)
+
+- Package scaffold `infra-mcp/` (workspace, biome, tsconfig, bun test, catalog deps; zod 4 catalog entry).
+- SDK v2 `/mcp` endpoint (`createMcpHandler`, `legacy: "stateless"`, `toNodeHandler`) mounted on a TerrenoApp/Express server.
+- Better Auth OAuth 2.1 (`@better-auth/oauth-provider` + `@better-auth/mcp`): discovery, login, token verify middleware.
+- RBAC wiring: `infraStatements`, default roles, `access.can()` authz middleware keyed on `Mcp-Name`, filtered `tools/list`. **Gated on the RBAC PR.**
+- Native adapters: gcp (ADC), sentry, mongo — read tools above.
+- `InfraAuditLog` + audit middleware.
+- Terraform: clone `mcp_service` module (new service name, Artifact Registry, runtime SA with viewer/log IAM roles only for now).
+- Tests: authz matrix (role × tool), tool handlers against mocks/emulators, audit records.
+- **Deliverable:** a teammate signs in from Cursor/Claude Code, gets exactly the tools their role allows, digs logs across GCP/Sentry/Mongo.
+
+### Phase 2 — Write tier + machine callers
+
+- Elicitation `confirmWrite` wrapper; config override gated by `infra:writeUnconfirmed`; fail-closed for non-elicitation clients.
+- Initial write tools (list above); runtime SA IAM widened only for the specific write APIs.
+- Service tokens (Better Auth `apiKey` spike → fallback `ServiceToken` model); machine users with `infra-readonly` role.
+- Cloud agent migration: agents get `INFRA_MCP_URL` + service token instead of `GCP_SA_*`; update AGENTS.md/environment docs; retire the env-injected SA keys.
+- **Deliverable:** write actions work with per-call confirmation; cloud agents dig logs through the MCP with no raw GCP credentials.
+
+### Phase 3 — Proxied adapters + remaining vendors
+
+- `ProxiedAdapter` (MCP client, stdio + HTTP transports, allow-list with mandatory tier annotations, name prefixing).
+- First proxied integration: `@sentry/mcp-server` (stdio, static token) or `observability-mcp` — pick one as the reference implementation and keep the native tools as fallback.
+- Native Expo/EAS tools (`EXPO_TOKEN`: builds, updates, submissions status) and Vercel tools (API token: deployments, logs).
+- **Deliverable:** adding a vendor MCP is config + annotations, not code.
+
+### Phase 4 — OSS packaging
+
+- `defineInfraMcp` config reference docs, quickstart (one-man-shop path: tokens + deploy anywhere a container runs), website docs page.
+- Publish `@terreno/infra-mcp`; bootstrap/MCP-server docs updates; changelog + upgrade notes.
+- **Deliverable:** an external startup can deploy their own instance from docs alone.
+
+## Feature Flags & Migrations
+
+- **No data migrations** — all collections are new.
+- Rollout is additive: new package, new Cloud Run service. Nothing existing changes until Phase 2's cloud-agent credential switch, which is coordinated: keep `GCP_SA_*` injection until the MCP path is verified, then remove.
+- RBAC dependency: the RBAC module is Complete ([rbac-permissions.md](rbac-permissions.md)). Phase 1 wiring consumes `createAccess`, `rbacUserPlugin`, `rbacRouter`, default-role seeding.
+
+## Activity Log & User Updates
+
+`InfraAuditLog` records every `tools/call` (allowed, denied, confirmed, rejected, error) with user attribution — this is the compliance answer for server-held credentials, since vendor-side logs only show the service identity. RBAC role changes are covered by the RBAC module's `RbacAudit`.
+
+## Not Included / Future Work
+
+- Per-user vendor identity for the write tier (credential interface takes user context; add later).
+- Rate limiting / quotas per user or tier.
+- Slack notifications on write actions.
+- Proxying interactive-OAuth-only vendor MCPs (Vercel/Expo hosted) — revisit if they ship headless credentials.
+- Terraform-apply / IaC tools (high blast radius; needs its own design).
+- MCP Tasks extension for long-running operations (EAS builds) — Phase 3+ candidate.
+
+## Files to Create / Modify
+
+- `infra-mcp/` — new package: `src/index.ts` (server entry), `src/server.ts`, `src/access.ts`, `src/config.ts`, `src/auth.ts`, `src/audit.ts` + `src/models/infraAuditLog.ts`, `src/integrations/{types,registry,gcp/*,sentry/*,mongo/*,proxied}.ts`, `src/types/models/*`, tests.
+- `package.json` (root) — workspace entry, catalog: zod 4, `@modelcontextprotocol/server`, `@better-auth/oauth-provider`, `@better-auth/mcp`, Google API clients.
+- `terraform/main.tf`, `variables.tf`, `outputs.tf` — `infra_mcp_service` module instance + runtime SA IAM.
+- `.cursor/rules/infra-mcp/00-infra-mcp.mdc`, `AGENTS.md`/`CLAUDE.md` package lists, docs site page.
+- `ROADMAP.md` + `docs/explanation/roadmap-seed-issues.md` — roadmap entry and ready-to-paste tracking issue (done); `scripts/issueAreaLabels.ts` + bug-report package dropdown when the package lands.
+
+## Task List
+
+See [docs/tasks/infra-mcp.md](../tasks/infra-mcp.md).
+
+## Acceptance Criteria
+
+- [ ] An MCP client completes OAuth against the deployed server and lists only the tools the signed-in user's roles allow.
+- [ ] A user with only `auditor`/`infra-readonly` can query GCP logs, Sentry issues, and Mongo collections, and cannot see or call any write tool.
+- [ ] A write-tier tool call triggers an elicitation prompt; declining aborts with an audited `rejected` status.
+- [ ] With `confirmWrites: false` configured, confirmation is skipped **only** for callers holding `infra:writeUnconfirmed`; all others are still prompted.
+- [ ] Every tool call (including denials) produces an `InfraAuditLog` record with user attribution and redacted args.
+- [ ] The deployed service runs with only the Cloud Run default runtime SA — no SA key files or `GCP_SA_*` env vars anywhere in the stack.
+- [ ] A cloud agent authenticates with a service token and reads logs; the `GCP_SA_*` env vars are removed from agent environments.
+- [ ] A 2025-era MCP client (pre-2026 spec) connects successfully via the legacy stateless fallback.
+- [ ] `bun run lint`, package tests, and CI pass.