cedar-mcp-server 1.0.0

package/examples/rbac-document-management/README.md

@@ -0,0 +1,167 @@
+# RBAC Document Management
+
+Role-based access control for a document system — the simplest Cedar pattern and the right place to start.
+
+## What this example covers
+
+Four roles (admin, editor, viewer, no-role), three actions (READ, WRITE, DELETE), and a `forbid` policy that blocks access to top-secret documents regardless of role. Demonstrates `cedar_authorize`, `cedar_validate`, `cedar_explain`, and `cedar_generate_sample_request`.
+
+## Quick start
+
+Configure the MCP server in Claude Code (`.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "cedar": {
+      "command": "npx",
+      "args": ["-y", "cedar-mcp-server"]
+    }
+  }
+}
+```
+
+Or run offline:
+
+```bash
+npx tsx examples/rbac-document-management/run.ts
+```
+
+## Files
+
+```
+schema.json                    Cedar schema — DocMgmt namespace
+policies/
+  admin.cedar                  Admins can do anything
+  editor.cedar                 Editors can read and write
+  viewer.cedar                 Viewers can only read
+  top-secret-forbid.cedar      Forbid top_secret access (except admins)
+entities/
+  users-and-docs.json          Alice (admin), Bob (editor), Charlie (viewer), Dave (no role)
+```
+
+---
+
+## Tool examples — copy and paste to Claude Code
+
+### cedar_validate
+
+```
+Validate these Cedar policies against the schema.
+
+Schema:
+[paste contents of schema.json]
+
+Policies:
+[paste all .cedar files]
+```
+
+Expected: valid, 4 policies, no errors.
+
+### cedar_authorize
+
+```
+Would Bob be allowed to read the document "acquisition-details"?
+
+Policies: [paste all .cedar files]
+Principal: DocMgmt::User::"bob"
+Action: DocMgmt::Action::"READ"
+Resource: DocMgmt::Document::"acquisition-details"
+Entities: [paste entities/users-and-docs.json]
+Schema: [paste schema.json]
+```
+
+Expected: **Deny** — the `top-secret-forbid` policy fires. Bob is an editor but that forbid overrides his permit.
+
+```
+Would Alice be allowed to read acquisition-details?
+```
+
+Expected: **Allow** — Alice is an admin. The `unless` clause in the forbid exempts admins.
+
+### cedar_explain
+
+```
+Explain this Cedar policy in plain English:
+
+forbid (
+  principal,
+  action,
+  resource
+)
+when {
+  resource.classification == "top_secret"
+}
+unless {
+  principal in DocMgmt::Role::"admin"
+};
+```
+
+Expected: a breakdown showing `forbid_policy`, `role_exemption`, the when/unless conditions in plain English.
+
+### cedar_generate_sample_request
+
+```
+Generate a sample request that would be DENIED by this policy:
+
+permit (
+  principal in DocMgmt::Role::"viewer",
+  action == DocMgmt::Action::"READ",
+  resource
+);
+
+Schema: [paste schema.json]
+```
+
+Expected: a complete entity payload with principal outside the viewer role.
+
+### cedar_check_policy_change
+
+```
+Can this policy change be applied in-place in Amazon Verified Permissions?
+
+Old policy:
+permit (
+  principal in DocMgmt::Role::"viewer",
+  action == DocMgmt::Action::"READ",
+  resource
+);
+
+New policy:
+permit (
+  principal in DocMgmt::Role::"senior_viewer",
+  action == DocMgmt::Action::"READ",
+  resource
+);
+```
+
+Expected: **cannot update in-place** — the principal clause changed. AVP requires delete and recreate.
+
+---
+
+## Test cases
+
+| Principal | Action | Resource | Expected | Reason |
+|-----------|--------|----------|----------|--------|
+| alice (admin) | READ | acquisition-details | **Allow** | Admin policy permits |
+| alice (admin) | DELETE | acquisition-details | **Allow** | Admin exempt from top_secret forbid |
+| bob (editor) | WRITE | roadmap-2026 | **Allow** | Editor can write |
+| bob (editor) | DELETE | roadmap-2026 | **Deny** | Editor cannot delete |
+| bob (editor) | READ | acquisition-details | **Deny** | top_secret forbid overrides editor permit |
+| charlie (viewer) | READ | public-announcement | **Allow** | Viewer can read |
+| charlie (viewer) | WRITE | public-announcement | **Deny** | Viewer cannot write |
+| charlie (viewer) | READ | acquisition-details | **Deny** | top_secret forbid overrides viewer permit |
+| dave (no role) | READ | public-announcement | **Deny** | Default deny — no matching permit |
+| dave (no role) | READ | acquisition-details | **Deny** | Default deny + top_secret forbid |
+
+---
+
+## Common pitfalls in this pattern
+
+**`forbid` overrides `permit` — always.** A single matching `forbid` blocks the request regardless of how many `permit` policies also match. If you add an admin `permit` and a top-secret `forbid`, the `unless { principal in Role::"admin" }` clause is what lets admins through — not some priority system.
+
+**Default deny is not a policy.** Cedar denies by default when no `permit` matches. Dave gets denied not because of a `forbid` but because no policy grants him anything. These are different: a `forbid` appears in `diagnostics.reason`; a default deny leaves `determining_policies` empty.
+
+**Role membership is transitive via `parents`.** `principal in DocMgmt::Role::"admin"` is true when the entity has `"admin"` anywhere in its parent chain — direct or inherited. If roles inherit from other roles, the `in` check follows the chain.
+
+**Schema validation catches attribute typos silently at runtime.** If you access `resource.clasification` (one `s`) without schema validation, Cedar silently makes the policy inapplicable rather than erroring. Always validate against the schema during development.

package/examples/rbac-document-management/entities/users-and-docs.json

@@ -0,0 +1,43 @@
+[
+  {
+    "uid": { "type": "DocMgmt::User", "id": "alice" },
+    "attrs": { "name": "Alice", "email": "alice@example.com" },
+    "parents": [{ "type": "DocMgmt::Role", "id": "admin" }]
+  },
+  {
+    "uid": { "type": "DocMgmt::User", "id": "bob" },
+    "attrs": { "name": "Bob", "email": "bob@example.com" },
+    "parents": [{ "type": "DocMgmt::Role", "id": "editor" }]
+  },
+  {
+    "uid": { "type": "DocMgmt::User", "id": "charlie" },
+    "attrs": { "name": "Charlie", "email": "charlie@example.com" },
+    "parents": [{ "type": "DocMgmt::Role", "id": "viewer" }]
+  },
+  {
+    "uid": { "type": "DocMgmt::User", "id": "dave" },
+    "attrs": { "name": "Dave", "email": "dave@example.com" },
+    "parents": []
+  },
+  { "uid": { "type": "DocMgmt::Role", "id": "admin" }, "attrs": {}, "parents": [] },
+  { "uid": { "type": "DocMgmt::Role", "id": "editor" }, "attrs": {}, "parents": [] },
+  { "uid": { "type": "DocMgmt::Role", "id": "viewer" }, "attrs": {}, "parents": [] },
+  {
+    "uid": { "type": "DocMgmt::Document", "id": "roadmap-2026" },
+    "attrs": { "owner": "alice", "classification": "internal" },
+    "parents": [{ "type": "DocMgmt::Folder", "id": "strategy" }]
+  },
+  {
+    "uid": { "type": "DocMgmt::Document", "id": "public-announcement" },
+    "attrs": { "owner": "alice", "classification": "public" },
+    "parents": [{ "type": "DocMgmt::Folder", "id": "comms" }]
+  },
+  {
+    "uid": { "type": "DocMgmt::Document", "id": "acquisition-details" },
+    "attrs": { "owner": "alice", "classification": "top_secret" },
+    "parents": [{ "type": "DocMgmt::Folder", "id": "confidential" }]
+  },
+  { "uid": { "type": "DocMgmt::Folder", "id": "strategy" }, "attrs": {}, "parents": [] },
+  { "uid": { "type": "DocMgmt::Folder", "id": "comms" }, "attrs": {}, "parents": [] },
+  { "uid": { "type": "DocMgmt::Folder", "id": "confidential" }, "attrs": {}, "parents": [] }
+]

package/examples/rbac-document-management/policies/admin.cedar

@@ -0,0 +1,6 @@
+// Admins can do anything on any document
+permit (
+  principal in DocMgmt::Role::"admin",
+  action,
+  resource
+);

package/examples/rbac-document-management/policies/editor.cedar

@@ -0,0 +1,6 @@
+// Editors can read and write, but not delete
+permit (
+  principal in DocMgmt::Role::"editor",
+  action in [DocMgmt::Action::"READ", DocMgmt::Action::"WRITE"],
+  resource
+);

package/examples/rbac-document-management/policies/top-secret-forbid.cedar

@@ -0,0 +1,13 @@
+// Nobody can access top-secret documents except admins
+// This forbid overrides all permit policies
+forbid (
+  principal,
+  action,
+  resource
+)
+when {
+  resource.classification == "top_secret"
+}
+unless {
+  principal in DocMgmt::Role::"admin"
+};

package/examples/rbac-document-management/policies/viewer.cedar

@@ -0,0 +1,6 @@
+// Viewers can only read
+permit (
+  principal in DocMgmt::Role::"viewer",
+  action == DocMgmt::Action::"READ",
+  resource
+);

package/examples/rbac-document-management/run.ts

@@ -0,0 +1,87 @@
+/**
+ * Offline runner for the rbac-document-management example.
+ * Runs each cedar-mcp-server tool against the example files and prints results.
+ *
+ * Usage: npx tsx examples/rbac-document-management/run.ts
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { handleAuthorize } from "../../src/tools/authorize.js";
+import { handleValidate } from "../../src/tools/validate.js";
+import { handleExplain } from "../../src/tools/explain.js";
+import { handleGenerateSample } from "../../src/tools/generate-sample.js";
+
+const dir = new URL(".", import.meta.url).pathname;
+const read = (p: string) => readFileSync(join(dir, p), "utf8");
+
+const schema = read("schema.json");
+const entities = read("entities/users-and-docs.json");
+
+const policies = [
+  read("policies/admin.cedar"),
+  read("policies/editor.cedar"),
+  read("policies/viewer.cedar"),
+  read("policies/top-secret-forbid.cedar"),
+].join("\n\n");
+
+function section(title: string) {
+  console.log(`\n${"─".repeat(60)}`);
+  console.log(`  ${title}`);
+  console.log("─".repeat(60));
+}
+
+// ─── cedar_validate ───────────────────────────────────────────────────────────
+
+section("cedar_validate — all policies against schema");
+const validateResult = await handleValidate({ policies, schema });
+console.log(`  valid: ${validateResult.valid}`);
+console.log(`  policies: ${validateResult.policy_count}`);
+if (validateResult.errors.length > 0) {
+  console.log("  errors:", validateResult.errors);
+}
+
+// ─── cedar_authorize ──────────────────────────────────────────────────────────
+
+section("cedar_authorize — 4 representative decisions");
+const authCases = [
+  { label: "alice (admin) reads acquisition-details", principal: 'DocMgmt::User::"alice"', action: 'DocMgmt::Action::"READ"', resource: 'DocMgmt::Document::"acquisition-details"', expected: "Allow" },
+  { label: "bob (editor) writes roadmap-2026", principal: 'DocMgmt::User::"bob"', action: 'DocMgmt::Action::"WRITE"', resource: 'DocMgmt::Document::"roadmap-2026"', expected: "Allow" },
+  { label: "bob (editor) reads acquisition-details (top_secret forbid)", principal: 'DocMgmt::User::"bob"', action: 'DocMgmt::Action::"READ"', resource: 'DocMgmt::Document::"acquisition-details"', expected: "Deny" },
+  { label: "dave (no role) reads public-announcement (default deny)", principal: 'DocMgmt::User::"dave"', action: 'DocMgmt::Action::"READ"', resource: 'DocMgmt::Document::"public-announcement"', expected: "Deny" },
+];
+
+for (const c of authCases) {
+  const r = await handleAuthorize({ policies, principal: c.principal, action: c.action, resource: c.resource, entities, schema });
+  const pass = r.decision === c.expected ? "✓" : "✗";
+  console.log(`  ${pass} ${c.label}: ${r.decision}`);
+  if (r.determining_policies.length > 0) console.log(`    determined by: ${r.determining_policies.join(", ")}`);
+}
+
+// ─── cedar_explain ────────────────────────────────────────────────────────────
+
+section("cedar_explain — editor policy");
+const explainResult = await handleExplain({ policy: read("policies/top-secret-forbid.cedar") });
+console.log(`  effect: ${explainResult.effect}`);
+console.log(`  summary: ${explainResult.summary}`);
+console.log(`  patterns: ${explainResult.patterns_detected.join(", ")}`);
+console.log(`  conditions:`);
+for (const c of explainResult.conditions) {
+  console.log(`    [${c.kind}] ${c.text}`);
+}
+
+// ─── cedar_generate_sample_request ───────────────────────────────────────────
+
+section("cedar_generate_sample_request — allow request for editor policy");
+const sampleResult = await handleGenerateSample({
+  policy: read("policies/editor.cedar"),
+  schema,
+  target_decision: "allow",
+});
+console.log(`  decision: ${sampleResult.decision}`);
+console.log(`  principal: ${sampleResult.principal}`);
+console.log(`  action: ${sampleResult.action}`);
+console.log(`  resource: ${sampleResult.resource}`);
+console.log(`  explanation: ${sampleResult.explanation}`);
+
+console.log("\n✓ All done.");

package/examples/rbac-document-management/schema.json

@@ -0,0 +1,57 @@
+{
+  "DocMgmt": {
+    "entityTypes": {
+      "User": {
+        "memberOfTypes": ["Role"],
+        "shape": {
+          "type": "Record",
+          "attributes": {
+            "name": { "type": "String", "required": true },
+            "email": { "type": "String", "required": true }
+          }
+        }
+      },
+      "Role": {
+        "memberOfTypes": [],
+        "shape": { "type": "Record", "attributes": {} }
+      },
+      "Document": {
+        "memberOfTypes": ["Folder"],
+        "shape": {
+          "type": "Record",
+          "attributes": {
+            "owner": { "type": "String", "required": true },
+            "classification": { "type": "String", "required": true }
+          }
+        }
+      },
+      "Folder": {
+        "memberOfTypes": [],
+        "shape": { "type": "Record", "attributes": {} }
+      }
+    },
+    "actions": {
+      "READ": {
+        "appliesTo": {
+          "principalTypes": ["User"],
+          "resourceTypes": ["Document"],
+          "context": { "type": "Record", "attributes": {} }
+        }
+      },
+      "WRITE": {
+        "appliesTo": {
+          "principalTypes": ["User"],
+          "resourceTypes": ["Document"],
+          "context": { "type": "Record", "attributes": {} }
+        }
+      },
+      "DELETE": {
+        "appliesTo": {
+          "principalTypes": ["User"],
+          "resourceTypes": ["Document"],
+          "context": { "type": "Record", "attributes": {} }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "cedar-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for Cedar policy language — validate, authorize, format, and translate Cedar policies directly in your AI assistant",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "cedar-mcp-server": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run --exclude 'test/integration/**'",
+    "test:integration": "vitest run test/integration",
+    "test:watch": "vitest --exclude 'test/integration/**'"
+  },
+  "dependencies": {
+    "@cedar-policy/cedar-wasm": "4.11.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@types/express": "^5.0.6",
+    "express": "^5.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "fast-check": "^4.8.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "cedar",
+    "mcp",
+    "model-context-protocol",
+    "authorization",
+    "policy",
+    "aws",
+    "verified-permissions"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pigius/cedar-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Pigius/cedar-mcp-server/issues"
+  },
+  "homepage": "https://github.com/Pigius/cedar-mcp-server#readme"
+}

package/src/http-server.ts

@@ -0,0 +1,239 @@
+import { createServer as createHttpServer, type Server as HttpServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import express from "express";
+import { createServer } from "./server.js";
+import { storeManager } from "./resources/store-manager.js";
+
+export interface HttpServerOptions {
+  port: number;
+  host?: string;
+  roots?: Array<{ name: string; path: string }>;
+  /** Max concurrent HTTP sessions. New sessions over the cap receive 503.
+   *  Default: 100. Override via env CEDAR_MAX_HTTP_SESSIONS or this option. */
+  maxSessions?: number;
+  /** Idle session TTL in milliseconds. A session unused for longer is evicted
+   *  by the reaper. Default: 30 minutes. Override via env
+   *  CEDAR_HTTP_SESSION_IDLE_TTL_MS or this option. */
+  sessionIdleTtlMs?: number;
+  /** How often the reaper scans for stale sessions. Default: 60 seconds.
+   *  Mostly relevant for tests; production deploys can leave the default. */
+  reaperIntervalMs?: number;
+}
+
+export interface RunningHttpServer {
+  httpServer: HttpServer;
+  port: number;
+  host: string;
+  close(): Promise<void>;
+}
+
+interface Session {
+  transport: StreamableHTTPServerTransport;
+  server: Awaited<ReturnType<typeof createServer>>;
+  /** Wall-clock timestamp of the last request observed on this session.
+   *  Used by the reaper to evict idle sessions. */
+  lastActiveAt: number;
+}
+
+const DEFAULT_MAX_SESSIONS = 100;
+const DEFAULT_SESSION_IDLE_TTL_MS = 30 * 60 * 1000; // 30 min
+const DEFAULT_REAPER_INTERVAL_MS = 60 * 1000;       // 1 min
+
+/**
+ * Boot cedar-mcp-server in Streamable HTTP mode.
+ *
+ * Per-session model: each MCP session gets its own McpServer + transport pair.
+ * The Streamable HTTP spec mandates this because each session has independent
+ * protocol state (initialized handshake, message history, capabilities).
+ *
+ * Shared across all sessions: the storeManager singleton. The deployment model
+ * is "one server per policy-store set, many team clients all seeing the same
+ * roots." Roots are deployer-configured via CLI flags at startup; client
+ * listRoots() is NOT called in HTTP mode. For per-tenant isolation, deploy
+ * multiple processes.
+ *
+ * Resource management:
+ *   - Max-sessions cap: new sessions over the limit receive HTTP 503. This is
+ *     backpressure, not eviction — existing sessions are not interrupted to
+ *     make room. Default 100; override via maxSessions option or
+ *     CEDAR_MAX_HTTP_SESSIONS env var.
+ *   - Idle TTL: a reaper scans periodically and evicts sessions whose last
+ *     observed request exceeds the TTL. Default 30 min idle / 60s scan;
+ *     override via sessionIdleTtlMs / reaperIntervalMs options or env vars.
+ *     This catches the case where transport.onclose doesn't fire (e.g.,
+ *     network partition, TCP RST) and prevents the sessions map from leaking.
+ *
+ * Session lifecycle:
+ *   1. Client POSTs to /mcp without Mcp-Session-Id → server creates a new
+ *      session (transport + server pair), runs initialize, returns the
+ *      session ID in the response header. New sessions over maxSessions are
+ *      rejected with HTTP 503.
+ *   2. Subsequent requests with that Mcp-Session-Id route to the same pair
+ *      and refresh its lastActiveAt timestamp.
+ *   3. transport.onclose fires on graceful disconnect → session removed.
+ *   4. Reaper sweeps idle sessions out periodically as a backstop.
+ */
+export async function startHttpServer(options: HttpServerOptions): Promise<RunningHttpServer> {
+  const host = options.host ?? "127.0.0.1";
+  const maxSessions = options.maxSessions
+    ?? (Number(process.env.CEDAR_MAX_HTTP_SESSIONS) || DEFAULT_MAX_SESSIONS);
+  const sessionIdleTtlMs = options.sessionIdleTtlMs
+    ?? (Number(process.env.CEDAR_HTTP_SESSION_IDLE_TTL_MS) || DEFAULT_SESSION_IDLE_TTL_MS);
+  const reaperIntervalMs = options.reaperIntervalMs ?? DEFAULT_REAPER_INTERVAL_MS;
+
+  // Load deployer-configured roots before the server starts accepting traffic.
+  // Shared by all sessions via the storeManager singleton.
+  if (options.roots && options.roots.length > 0) {
+    storeManager.loadFromRoots(
+      options.roots.map((r) => ({ uri: `file://${r.path}`, name: r.name }))
+    );
+  }
+
+  const sessions = new Map<string, Session>();
+
+  async function createSession(): Promise<Session> {
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+    });
+    const server = createServer();
+    await server.connect(transport);
+
+    transport.onclose = () => {
+      // Only drop the session-map entry here. Do NOT call server.close():
+      // server.close() triggers transport close, which fires this handler
+      // again. The McpServer becomes unreferenced and gets GC'd. The shared
+      // WASM module lives at process scope, not per-session.
+      const sid = transport.sessionId;
+      if (sid && sessions.has(sid)) {
+        sessions.delete(sid);
+      }
+    };
+
+    return { transport, server, lastActiveAt: Date.now() };
+  }
+
+  // Reaper: evict sessions whose lastActiveAt is older than the idle TTL.
+  // Collect-then-delete pattern avoids mid-iteration map mutation when the
+  // transport.close() callback re-enters the sessions map.
+  const reaper = setInterval(() => {
+    const cutoff = Date.now() - sessionIdleTtlMs;
+    const toEvict: string[] = [];
+    for (const [sid, sess] of sessions.entries()) {
+      if (sess.lastActiveAt < cutoff) toEvict.push(sid);
+    }
+    for (const sid of toEvict) {
+      const sess = sessions.get(sid);
+      if (sess) {
+        sessions.delete(sid);
+        void sess.transport.close().catch(() => { /* ignore */ });
+      }
+    }
+  }, reaperIntervalMs);
+  // Don't keep the Node event loop alive just for the reaper — let the
+  // process exit cleanly when the HTTP server closes.
+  reaper.unref();
+
+  const app = createMcpExpressApp({ host });
+  app.use(express.json({ limit: "10mb" }));
+
+  app.post("/mcp", async (req, res) => {
+    try {
+      const sessionIdHeader = req.headers["mcp-session-id"];
+      const sessionId = Array.isArray(sessionIdHeader) ? sessionIdHeader[0] : sessionIdHeader;
+
+      let session: Session | undefined;
+      if (sessionId && sessions.has(sessionId)) {
+        session = sessions.get(sessionId);
+        if (session) session.lastActiveAt = Date.now();
+      } else {
+        // New session — apply backpressure if at cap. We do this BEFORE
+        // creating the transport/server pair to avoid leaking resources
+        // on rejection.
+        if (sessions.size >= maxSessions) {
+          res.status(503).json({
+            error: "Too many concurrent MCP sessions",
+            message: `Server is at the max-session limit of ${maxSessions}. Try again later, or run multiple processes for higher capacity.`,
+            active_sessions: sessions.size,
+            max_sessions: maxSessions,
+          });
+          return;
+        }
+        session = await createSession();
+      }
+
+      if (!session) {
+        res.status(400).json({ error: "Could not establish MCP session" });
+        return;
+      }
+
+      await session.transport.handleRequest(req, res, req.body);
+
+      // After the initialize request completes the transport will have set
+      // its sessionId. Register the session under that ID so subsequent
+      // requests find it.
+      const sidAfter = session.transport.sessionId;
+      if (sidAfter && !sessions.has(sidAfter)) {
+        sessions.set(sidAfter, session);
+      }
+    } catch (e) {
+      if (!res.headersSent) {
+        res.status(500).json({
+          error: "Internal MCP transport error",
+          message: e instanceof Error ? e.message : String(e),
+        });
+      }
+    }
+  });
+
+  app.get("/health", (_req, res) => {
+    res.json({
+      status: "ok",
+      transport: "streamable-http",
+      mode: "stateful",
+      active_sessions: sessions.size,
+      max_sessions: maxSessions,
+      session_idle_ttl_ms: sessionIdleTtlMs,
+    });
+  });
+
+  const httpServer = createHttpServer(app);
+
+  await new Promise<void>((resolve, reject) => {
+    httpServer.once("error", reject);
+    httpServer.listen(options.port, host, () => {
+      httpServer.off("error", reject);
+      resolve();
+    });
+  });
+
+  // eslint-disable-next-line no-console
+  console.error(`[cedar-mcp-server] Streamable HTTP listening on http://${host}:${options.port}/mcp (max_sessions=${maxSessions}, idle_ttl=${Math.round(sessionIdleTtlMs / 1000)}s)`);
+  if (options.roots && options.roots.length > 0) {
+    // eslint-disable-next-line no-console
+    console.error(`[cedar-mcp-server] Loaded ${options.roots.length} root(s): ${options.roots.map((r) => r.name).join(", ")}`);
+  } else {
+    // eslint-disable-next-line no-console
+    console.error("[cedar-mcp-server] WARNING: no --root flags supplied; tools that depend on a configured store will error.");
+  }
+
+  return {
+    httpServer,
+    port: options.port,
+    host,
+    async close() {
+      clearInterval(reaper);
+      // Close all sessions first so each McpServer cleans up its WASM state
+      for (const session of sessions.values()) {
+        try {
+          await session.server.close();
+        } catch { /* ignore */ }
+      }
+      sessions.clear();
+      await new Promise<void>((resolve, reject) => {
+        httpServer.close((err) => (err ? reject(err) : resolve()));
+      });
+    },
+  };
+}