decision: default wiring for the serve-side MCP server (@objectstack/mcp) in dev — identity admission first

[os-zhuang]

Decision issue — direction first, implementation split later. Counterpart of the consume-side work that closed #2977/#3056: those made ObjectStack call external MCP servers; this is about ObjectStack being one.

Current state (verified against main)

An odd half-wired shape:

• The runtime dispatcher already serves an MCP HTTP surface per-request at /api/v1/mcp, default-ON (OS_MCP_SERVER_ENABLED=false opts out), plus the public GET /api/v1/mcp/skill SKILL.md download and a connect UI (packages/mcp/src/connect-ui.ts).
• But the service behind it — MCPServerPlugin (registers the 'mcp' service; bridges ToolRegistry, MetadataService, DataEngine, and Agents; optionally starts a long-lived stdio transport via autoStart / OS_MCP_SERVER_ENABLED=true) — is wired nowhere by default: not in os dev/serve, not in the showcase, not in the scaffold. Its only in-repo consumer is an app-todo e2e.

Net effect: an AI-native platform whose official "let AI operate the running app" channel is a route that answers but a capability that is never registered. Discoverability is zero exactly where the platform's pitch is strongest — the dev loop, where a coding agent (Claude Code, Cursor, any MCP client) could read the schema, inspect seed data, and exercise actions of the app it is building.

Proposed direction (to be ratified or amended)

Dev default-on, prod explicit. os dev registers MCPServerPlugin by default (escape hatch: OS_MCP_SERVER_ENABLED=false); os serve/production keeps today's explicit opt-in. The value asymmetry is stark: in dev the MCP endpoint completes the AI-builds-apps loop; in prod it is a high-authority execution surface that must be a deliberate choice.

The four decisions to make (in order)

1. Identity admission — hard precondition (ADR-0096)

MCP tool execution is an execution surface, the same class as GraphQL and realtime, which ADR-0096 registered in the authz conformance matrix (packages/qa/dogfood/test/authz-conformance.matrix.ts) with CI tripwires. Today the matrix covers MCP only incidentally (the data-write ingress readonly strip names the MCP dispatcher as one funneled caller); there is no row for the MCP tool-execution principal: when an MCP client calls tools/call, whose ExecutionContext runs it? Dev-admin? A token-resolved user? An explicit guest? Fall-open on a missing principal = full authority — the exact failure mode ADR-0096 exists to prevent. Registering the row (and the answer) is the gate for any default-on wiring; nothing else in this issue proceeds before it.

2. The dev/prod boundary definition

What is "dev" for this purpose — the os dev command itself (recommended: wiring follows the command, not the env), NODE_ENV, or a config flag? And the off-switch semantics (OS_MCP_SERVER_ENABLED=false today disables the HTTP surface — should it also gate the plugin registration?).

3. Transport & mount shape

The per-request HTTP surface already exists; the open questions are (a) whether dev auto-start should also cover the stdio transport (local AI tools spawning the process directly — likely no: os dev owns the process), and (b) whether the connect UI / skill download need dev-specific affordances (e.g. printing the MCP URL + connect instructions on dev boot, which the dispatcher's skill/connect-ui pieces suggest was the intent).

4. Default exposure scope

Auto-generating tools for every object's CRUD explodes the tool list on real apps (hundreds of tools makes MCP clients unusable) and widens the misuse surface. Decide the default: e.g. only apiEnabled objects + explicitly marked actions/flows, with a metadata-declared exposure config as the future story (consistent with the ADR-0097 metadata-first philosophy — what is exposed should itself be authorable).

Optional extension (after the above)

With a stable in-repo serve-side endpoint, the showcase's declarative provider: 'mcp' connector gains a second demo target: the platform connecting to itself. Previously rejected for boot-ordering (automation start() runs before HTTP listens); the #3049 degrade+retry makes the self-connection heal seconds after boot, but the dogfood gate must not become timing-sensitive — treat as a separate, carefully-gated follow-up.

Refs

• ADR-0096 (execution-surface identity admission — the matrix + tripwire mechanism this must register with)
• ADR-0097 / Implement ADR-0096: declarative connector instances (provider-bound connectors: materialized by generic executors) #2977 / feat: default preset includes the three generic connector executors (rest / openapi / mcp) — blocked by #3055 #3056 (consume side, closed), ADR-0024 §4 (trust model)
• packages/mcp (MCPServerPlugin, MCPServerRuntime, connect-ui, skill), packages/runtime/src/http-dispatcher.ts (/mcp routes)

[os-zhuang]

Correction after auditing the code — decision 1's premise was wrong, and it sharpens decision 4

Implementing the identity-admission step (PR #3202) surfaced that the issue mis-stated the current state. Two corrections:

Decision 1 — the HTTP admission is already wired, not missing

The issue claimed "there is no row for the MCP tool-execution principal… fall-open on a missing principal = full authority." Reading handleMcp (runtime/http-dispatcher.ts) and the MCP runtime, the HTTP surface actually does admit the caller:

• Anonymous denied — handleMcp requires ec.userId || ec.isSystem, else 401 (with an RFC 9728 WWW-Authenticate when the OAuth track is live).
• Scope-gated — OAuth-token provenance narrows the exposed tool families to the granted MCP scopes; a token granting none gets 403 (feat(mcp): OAuth 2.1 authorization for /api/v1/mcp (self-serve connect from claude.ai / Claude Code / Desktop) #2698).
• Caller-scoped execution — buildMcpBridge(context) threads the caller ExecutionContext into every bridge op (callData(..., ec)), and handleHttpRequest builds a fresh per-request McpServer from that principal-bound bridge. So RLS / FLS / tenant apply exactly as on REST /data.

So decision 1 is not "build identity admission" — it's "pin the admission that exists so a refactor can't silently drop it, and register the one transport that genuinely lacks it." PR #3202 does both: an enforced mcp-http-identity row (pinned by handleMcp + buildMcpBridge(context) probes) and an experimental mcp-stdio-authority row.

The real gap: the stdio transport runs unscoped

MCPServerPlugin.start() bridges the raw metadata service + data engine onto the long-lived server (bridgeResources(metadataService, dataEngine)) with no per-request principal — a stdio-attached client reads with full, unscoped authority. This is safe only as a single-operator local tool (whoever can attach stdio already owns the process + dev DB), and it is deliberately not default (the shouldStart opt-in gate). The mcp-stdio-authority row records this posture and states the admission requirement before stdio is ever promoted to default-on / multi-user: thread a principal into the long-lived bridge, mirroring the HTTP path.

This also sharpens decision 4 (per-object vs unified tools)

Related audit finding (raised separately): the exposure surface is already the unified/parameterized shape the issue's decision 4 worried about avoiding — list_objects / describe_object / query_records / get_record / … are a fixed ~10-tool spine with the object name as a parameter (registerObjectTools), and actions are list_actions + run_action(name, …), not one tool per action. So decision 4 is not "per-object vs unified" (settled in code) — the open questions are narrower: the default exposure policy (which objects/actions are in scope; today: non-system + author AI opt-in for actions) and whether a few high-value actions warrant typed per-action tools on top of the generic spine.

Net effect on the roadmap

• Decision 1 → largely done as an accounting/pinning step (PR test(authz): register MCP execution-surface identity admission in the ADR-0096 matrix (#3167) #3202); the remaining piece is the HTTP surface's e2e dogfood proof, which belongs with PR-B (the os dev default-wiring).
• Decisions 2 / 3 (dev/prod boundary, transport shape) → unchanged, still for maintainer direction.
• Decision 4 → reframe as exposure policy, not tool topology.

PR #3202 is test-only (matrix rows + probes in the private @objectstack/dogfood gate), no runtime change, no os dev wiring — so it's safe to land ahead of the direction call, and it makes the stdio gap a CI-pinned fact rather than a latent surprise.

---

Generated by Claude Code

[os-zhuang]

Direction ratified — dev default-on approved; execution plan below

Maintainer decision (following the audit + correction above). Recording each of the four decisions in its final state:

✅ Decision A (the product call): os dev wires the MCP server by default

Approved. Rationale accepted: risk-equivalence — the MCP HTTP surface rides the same callData ingress as REST /data with the same admission (anonymous 401, OAuth scope gating, caller-EC threading; all CI-pinned since #3202), so a default-on MCP dev surface adds no authority REST dev does not already expose. run_action stays double-gated (author AI opt-in + caller permissions). Production keeps explicit opt-in — the value/risk asymmetry between dev and prod is the whole point.

✅ Decision B: HTTP surface only — stdio stays opt-in

The long-lived stdio transport is exactly the unscoped path registered as mcp-stdio-authority (#3202): it claims the process's stdin/stdout and reads with process authority. Default-on dev wiring therefore covers the per-request HTTP surface only; stdio remains behind autoStart / OS_MCP_SERVER_ENABLED=true, unchanged.

✅ Decision C: "dev" = the os dev command, not NODE_ENV; one off-switch gates both halves

Wiring follows explicit intent (the command), never an env that can leak into production-like deployments. OS_MCP_SERVER_ENABLED=false today disables only the HTTP route while plugin registration is a separate gate — PR-B unifies it: one switch turns off the route AND skips the dev registration, eliminating the half-off state.

✅ Decision D (reframed as exposure policy): ship the current defaults, defer declarative config

The unified parameterized tool spine (settled in code) with today's visibility set — non-system objects + author AI opt-in for actions + OAuth scope families — ships as-is. A metadata-declared per-object exposure config is deferred until a real need appears (ADR-0049: no speculative config surface).

Execution plan — PR-B

Precondition (verify, don't assume): walk the dev connection path end-to-end first — how a developer's MCP client actually obtains a working credential against os dev (API key? OAuth bootstrap via the RFC 9728 advertisement? how many steps?). The connect-ui + GET /api/v1/mcp/skill pieces suggest this was designed; PR-B's boot-time guidance must reflect the actual shortest path, and if the path is long, tightening it is in scope.

Then the wiring PR:

1. os dev registers MCPServerPlugin (HTTP surface only), gated by the unified OS_MCP_SERVER_ENABLED switch;
2. off-switch unification (route + registration, one decision point);
3. dev-boot connect guidance: print the MCP URL, skill download, and connect-UI pointer;
4. e2e dogfood proof for the HTTP surface (anonymous → 401; principal → RLS/FLS-scoped tool results), upgrading the mcp-http-identity row to high-risk with its proof — closing the deferral noted on that row in test(authz): register MCP execution-surface identity admission in the ADR-0096 matrix (#3167) #3202.

Issue stays open until PR-B lands. The optional showcase self-connection demo remains out of scope (separately gated, per the original issue).

---

Generated by Claude Code

[os-zhuang]

PR-B 落地 + 四项决策的综合(实现已按此方向,开放确认/修正)

在 PR-A(#3202,静态记账)之上,#3167 中不需要进一步争论的部分已在 PR #3217 落地。基于审计发现(HTTP 面早已默认接线且已准入),四项决策的收敛如下:

Decision 1 — 身份准入 ✅ 完成

PR-A 静态钉住,PR-B 补上运行时 e2e 证明:按 os dev/serve 默认接线方式启动插件,驱动 POST /api/v1/mcp 证明匿名→401、principal 的工具结果被 RLS 裁剪、且 MCP 的可见 id 集合 == REST /data。mcp-http-identity 行从「proof deferred」翻成 proven。

Decision 2 — dev/prod 边界 + off-switch:追认全默认开 + 拆分开关

• 不退回「dev 开 / prod 关」的原提案:e2e 已证明 HTTP 面与 REST /data 是同一准入(不多一分权限),为它单独关 prod 闸在逻辑上等价于关掉 GraphQL——无理由,且是 breaking。「prod 谨慎」交给 Decision 4 承担。
• 修掉真正的 footgun:OS_MCP_SERVER_ENABLED=true 过去会静默附带启动无 scope 的 stdio 裸桥。已拆分 —— stdio 归独立的 OS_MCP_STDIO_ENABLED(默认关),旧 =true 触发保留一个 release + deprecation 警告。

Decision 3 — transport 形态

• stdio 坚决不进 dev 默认:os dev 拥有进程(生命周期不匹配),且 stdio 目前无 principal(见 mcp-stdio-authority 的准入要求)。HTTP 面已覆盖「本机 AI 工具连运行中 app」的全部场景。
• dev 连接指引已做:os dev 启动即打印 endpoint / skill / claude mcp add 命令。

Decision 4 — 从「工具拓扑」改判为「暴露政策」

现状(非系统对象 + ai.exposed action、object 名做参数的 ~10 工具脊柱)已在 connect-mcp.mdx 成文为 v1 政策;metadata 可著述的暴露配置(对象级 opt-out、高价值 action 的 typed 工具)列为后续。

---

仍 defer(单独 PR / 单独评审)

• stdio principal 线程化:把长驻 bridge 升级为 principal-bound,是把 mcp-stdio-authority 从 experimental 提升的前置——安全改动,单独走。
• showcase 自连接 demo:feat(connectors): degrade + retry declarative instances on unreachable upstream (#3017) #3049 的 degrade+retry 让它能自愈,但 dogfood gate 不能变 timing-sensitive,需显式 poll-until-ready,单独 PR。

方向如有需要调整,PR #3217 上直接提即可。

---

Generated by Claude Code

[os-zhuang]

PR-B (#3225) — a second correction: the wiring was already shipped

Building PR-B surfaced that decisions A / B / C are already implemented on main, and have been:

• serve.ts auto-loads MCPServerPlugin via requires.push('mcp') when isMcpServerEnabled() — the same decision point that gates the dispatcher's /mcp route, so the route and the plugin can never disagree. os dev inherits it by spawning os serve --dev.
• The off-switch is already unified (isMcpServerEnabled = one decision point for route + plugin load) — decision C done.
• stdio stays opt-in (autoStart / explicit true) — decision B done.
• It is in fact default-on for os serve (production) too, not just dev — a stronger posture than decision A, and a defensible one now that PR-A established the HTTP admission is enforced (anonymous-deny + scope-gate + caller-EC threading + RLS/FLS). I did not narrow prod to opt-in: that would reverse an existing shipped decision (feat(mcp): OAuth 2.1 authorization for /api/v1/mcp (self-serve connect from claude.ai / Claude Code / Desktop) #2698), and the safety argument (the surface is admitted) holds in prod too.

My earlier "wired nowhere by default" claim was a stale read — I grepped packages/tools/cli (which doesn't exist); the CLI is packages/cli. Apologies for the noise; the correction is now on the record.

So the only genuinely-missing piece was the e2e proof the mcp-http-identity row (#3202) deferred — which PR #3225 lands: a dogfood test boots the real showcase + security + MCP and proves anonymous /api/v1/mcp → 401 and a member's query_records is RLS-scoped to their own rows (would leak cross-owner if it ran unscoped). The matrix row is upgraded to high-risk + proof, closing that deferral.

Remaining, and my recommendation to close this issue after #3225

Everything the issue set out to decide is resolved:

• A — default-on: done + justified (admission enforced).
• B — stdio opt-in: done.
• C — unified off-switch: done.
• D — exposure policy: shipped defaults accepted; declarative exposure config deferred (ADR-0049), tracked separately if/when needed.

The one optional leftover is a DX nicety: printing the MCP connect URL / skill / connect-UI pointer on os dev boot. It is not an admission or correctness gap — the endpoint already works and advertises itself via the RFC 9728 WWW-Authenticate + GET /api/v1/mcp/skill. I'd suggest closing #3167 once #3225 merges and filing the boot-hint as a small standalone DX issue if wanted, rather than holding this issue open on polish.

The optional showcase self-connection demo remains out of scope, as originally stated.

---

Generated by Claude Code