[EPIC] Native MCP interface for Noosphere

[salim4n]

Goal

Expose Noosphere as a first-class remote MCP server while preserving the existing modular-monolith architecture, durable execution model, workspace isolation, deterministic policies, and provider authority rules.

The MCP surface must be an inbound adapter of the existing Noosphere application, not a second business backend.

Target architecture

MCP client
  -> HTTPS /mcp
  -> apps/api
  -> MCP interface adapter
  -> shared Noosphere application/runtime
  -> application ports
  -> infrastructure / durable jobs / outbox

Non-goals

• No standalone MCP microservice for v1.
• No MCP -> REST loopback calls.
• No direct Drizzle/PostgreSQL access from MCP tool handlers.
• No direct provider calls from MCP tools.
• No workspace ID supplied by the model as an authority source.
• No long-running business operation owned by an MCP HTTP connection.
• No mutable prospect/session state stored in MCP process memory.

Core principles

• workspaceId, userId, current workspace role and granted MCP scopes come from authenticated server-side context.
• Effective permission = OAuth scope ∩ current workspace role ∩ deterministic business policy.
• Read tools reuse existing redaction and authorization semantics.
• Mutations reuse application use cases, idempotency and audit facilities.
• Long-running work returns durable operation/job handles.
• External effects flow through existing approval/policy/outbox/worker/reconciliation mechanisms.
• MCP transport is stateless and deploys in the existing api container on the same VPS.

Delivery slices

• [MCP] Extract reusable Noosphere application runtime and enforce adapter boundaries #70 — Extract reusable Noosphere application runtime and enforce adapter boundaries
• [MCP] Add stateless MCP transport to apps/api and production routing #71 — Add stateless MCP transport to apps/api and production routing
• [MCP] Implement OAuth 2.1 authorization bound to Noosphere workspaces #72 — Implement OAuth 2.1 authorization bound to Noosphere workspaces
• [MCP] Expose first read-only tools and resources for GTM context #73 — Expose first read-only tools and resources for GTM context
• [MCP] Add safe internal write tools with idempotency, audit and concurrency control #74 — Add safe internal write tools with idempotency, audit and concurrency control
• [MCP] Represent long-running Noosphere jobs as durable operation handles #75 — Represent long-running Noosphere jobs as durable operation handles
• [MCP] Gate external effects through Noosphere approvals and policy revalidation #76 — Gate external effects through Noosphere approvals and policy revalidation
• [MCP] Security hardening, observability, compatibility tests and production canary #77 — Security hardening, observability, compatibility tests and production canary

Suggested implementation order

#70
  -> #71
      -> #72
      -> #73
          -> #74
          -> #75
              -> #76
                  -> #77

#73 can be developed against local/dev authentication while #72 is being completed; production remote access remains gated by OAuth.

Definition of done

A supported MCP client can authenticate to one Noosphere workspace, inspect its authorized GTM state, invoke supported internal actions, launch durable work, and safely propose governed external actions without bypassing any domain authority or tenant boundary.

[salim4n]

Epic completed.

All delivery slices #70 through #77 have been implemented and validated on main. The final production-readiness checkpoint is eb21541c5e9def20bb216f8f9adce57fd9d488b6; the dated evidence is in docs/validation/2026-08-30-mcp-production-canary.md.

The resulting MCP surface is hosted by the existing API/Caddy topology, uses durable OAuth and workspace authority, preserves tenant/RBAC/policy boundaries, supports safe reads/internal writes/durable operations/governed external effects, and has production-style SDK/Inspector, restart, integration, E2E, audit and image-scan evidence. No real provider mutation or release tag was performed as part of the canary.