@casys/mcp-server 0.12.0 → 0.13.0

package/README.md

@@ -4,9 +4,12 @@
 [![JSR](https://jsr.io/badges/@casys/mcp-server)](https://jsr.io/@casys/mcp-server)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-**The "Hono for MCP"** — a production-grade framework for building Model Context Protocol servers in TypeScript.
+**The "Hono for MCP"** — a production-grade framework for building Model Context
+Protocol servers in TypeScript.
 
-Composable middleware, OAuth2 auth, dual transport, observability, and everything you need to ship reliable MCP servers. Built on the official [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk).
+Composable middleware, OAuth2 auth, dual transport, observability, and
+everything you need to ship reliable MCP servers. Built on the official
+[@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk).
 
 ```
 rate-limit → auth → custom middleware → scope-check → validation → backpressure → handler
@@ -16,7 +19,8 @@ rate-limit → auth → custom middleware → scope-check → validation → bac
 
 ## Why @casys/mcp-server?
 
-The official SDK gives you the protocol. This framework gives you the production stack.
+The official SDK gives you the protocol. This framework gives you the production
+stack.
 
 |                         | Official SDK |       @casys/mcp-server        |
 | ----------------------- | :----------: | :----------------------------: |
@@ -51,9 +55,9 @@ deno add jsr:@casys/mcp-server
 ### STDIO Server (5 lines)
 
 ```typescript
-import { ConcurrentMCPServer } from "@casys/mcp-server";
+import { McpApp } from "@casys/mcp-server";
 
-const server = new ConcurrentMCPServer({ name: "my-server", version: "1.0.0" });
+const server = new McpApp({ name: "my-server", version: "1.0.0" });
 
 server.registerTool(
   {
@@ -74,12 +78,9 @@ await server.start();
 ### HTTP Server with Auth
 
 ```typescript
-import {
-  ConcurrentMCPServer,
-  createGoogleAuthProvider,
-} from "@casys/mcp-server";
+import { createGoogleAuthProvider, McpApp } from "@casys/mcp-server";
 
-const server = new ConcurrentMCPServer({
+const server = new McpApp({
   name: "my-api",
   version: "1.0.0",
   maxConcurrent: 10,
@@ -156,7 +157,8 @@ const timing: Middleware = async (ctx, next) => {
 server.use(timing);
 ```
 
-Built-in pipeline: `rate-limit → auth → custom → scope-check → validation → backpressure → handler`
+Built-in pipeline:
+`rate-limit → auth → custom → scope-check → validation → backpressure → handler`
 
 ### OAuth2 / JWT Auth
 
@@ -164,9 +166,9 @@ Four OIDC presets out of the box:
 
 ```typescript
 import {
-  createGoogleAuthProvider, // Google OIDC
   createAuth0AuthProvider, // Auth0
   createGitHubAuthProvider, // GitHub Actions OIDC
+  createGoogleAuthProvider, // Google OIDC
   createOIDCAuthProvider, // Generic OIDC (Keycloak, Okta, etc.)
 } from "@casys/mcp-server";
 
@@ -191,7 +193,8 @@ const provider = new JwtAuthProvider({
 });
 ```
 
-Token verification is cached (SHA-256 hash → AuthInfo, TTL = min(token expiry, 5min)) to avoid redundant JWKS round-trips.
+Token verification is cached (SHA-256 hash → AuthInfo, TTL = min(token expiry,
+5min)) to avoid redundant JWKS round-trips.
 
 ### YAML + Env Config
 
@@ -217,7 +220,9 @@ Priority: `programmatic > env vars > YAML > no auth`
 
 ### RFC 9728
 
-When auth is configured, the framework automatically exposes `GET /.well-known/oauth-protected-resource` per [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728).
+When auth is configured, the framework automatically exposes
+`GET /.well-known/oauth-protected-resource` per
+[RFC 9728](https://www.rfc-editor.org/rfc/rfc9728).
 
 ### Observability
 
@@ -272,7 +277,7 @@ Three backpressure strategies when the server is at capacity:
 | `reject`          | Fail fast with immediate error             |
 
 ```typescript
-new ConcurrentMCPServer({
+new McpApp({
   maxConcurrent: 10,
   backpressureStrategy: "queue",
 });
@@ -283,7 +288,7 @@ new ConcurrentMCPServer({
 Sliding window rate limiter with per-client tracking:
 
 ```typescript
-new ConcurrentMCPServer({
+new McpApp({
   rateLimit: {
     maxRequests: 100,
     windowMs: 60_000,
@@ -293,15 +298,19 @@ new ConcurrentMCPServer({
 });
 ```
 
-For HTTP endpoints, use `startHttp({ ipRateLimit: ... })` to rate limit by client IP (or custom key).
+For HTTP endpoints, use `startHttp({ ipRateLimit: ... })` to rate limit by
+client IP (or custom key).
 
 ### Security Best Practices (Tool Handlers)
 
 Tool handlers receive **untrusted JSON input**. Treat args as hostile:
 
-- **Define strict schemas**: `additionalProperties: false`, `minLength`, `pattern`, `enum`.
-- **Never pass raw args to a shell** (`Deno.Command`, `child_process.exec`). If you must, use an allowlist + argv array (no shell).
-- **Validate paths & resources**: allowlisted roots, deny `..`, restrict env access.
+- **Define strict schemas**: `additionalProperties: false`, `minLength`,
+  `pattern`, `enum`.
+- **Never pass raw args to a shell** (`Deno.Command`, `child_process.exec`). If
+  you must, use an allowlist + argv array (no shell).
+- **Validate paths & resources**: allowlisted roots, deny `..`, restrict env
+  access.
 - **Prefer safe APIs**: parameterized DB queries, SDK methods, typed clients.
 - **Log sensitive actions**: file writes, network calls, admin ops.
 
@@ -310,7 +319,7 @@ Tool handlers receive **untrusted JSON input**. Treat args as hostile:
 Register interactive UIs as MCP resources:
 
 ```typescript
-import { ConcurrentMCPServer, MCP_APP_MIME_TYPE } from "@casys/mcp-server";
+import { MCP_APP_MIME_TYPE, McpApp } from "@casys/mcp-server";
 
 server.registerResource(
   { uri: "ui://my-server/viewer", name: "Data Viewer" },
@@ -326,10 +335,15 @@ server.registerResource(
 
 ## API Reference
 
-### ConcurrentMCPServer
+### McpApp
+
+> **Note:** `ConcurrentMCPServer` and `ConcurrentServerOptions` remain exported
+> as `@deprecated` aliases for backwards compatibility and will be removed in
+> v1.0. New code should use `McpApp` / `McpAppOptions`. The aliases point to the
+> exact same class — `instanceof` checks pass on both.
 
 ```typescript
-const server = new ConcurrentMCPServer(options: ConcurrentServerOptions);
+const server = new McpApp(options: McpAppOptions);
 
 // Registration (before start)
 server.registerTool(tool, handler);

package/mod.ts

@@ -1,33 +1,32 @@
 /**
- * MCP Concurrent Server Framework
+ * @casys/mcp-server — Hono-style framework for MCP servers
  *
- * Production-ready MCP server framework with built-in concurrency control,
- * backpressure strategies, and optional sampling support.
+ * Production-ready MCP server framework with built-in middleware pipeline,
+ * auth, concurrency control, backpressure, and observability.
  *
- * Built on top of the official @modelcontextprotocol/sdk with added
- * production features for reliability and performance.
+ * Built on top of the official @modelcontextprotocol/sdk.
  *
  * @example
  * ```typescript
- * import { ConcurrentMCPServer } from "@casys/mcp-server";
+ * import { McpApp } from "@casys/mcp-server";
  *
- * const server = new ConcurrentMCPServer({
+ * const app = new McpApp({
  *   name: "my-server",
  *   version: "1.0.0",
  *   maxConcurrent: 10,
  *   backpressureStrategy: 'queue'
  * });
  *
- * server.registerTool(
+ * app.registerTool(
  *   { name: "greet", description: "Greet someone", inputSchema: { type: "object" } },
  *   (args) => `Hello, ${args.name}!`,
  * );
  *
  * // STDIO transport
- * await server.start();
+ * await app.start();
  *
  * // — or — HTTP transport with security-first defaults
- * const http = await server.startHttp({
+ * const http = await app.startHttp({
  *   port: 3000,
  *   maxBodyBytes: 1_048_576,                    // 1 MB (default)
  *   corsOrigins: ["https://app.example.com"],   // allowlist
@@ -39,8 +38,18 @@
  * @module @casys/mcp-server
  */
 
-// Main server class
-export { ConcurrentMCPServer } from "./src/concurrent-server.js";
+// Main server class — canonical name
+export { McpApp } from "./src/mcp-app.js";
+
+/**
+ * @deprecated Use {@link McpApp} instead. `ConcurrentMCPServer` is kept as
+ * a re-export for backwards compatibility and will be removed in v1.0.
+ *
+ * Both names point to the exact same class — `McpApp === ConcurrentMCPServer`
+ * is true at runtime, and `instanceof` checks pass in both directions.
+ * Migration is a one-line import swap.
+ */
+export { McpApp as ConcurrentMCPServer } from "./src/mcp-app.js";
 
 // Concurrency primitives
 export { RequestQueue } from "./src/concurrency/request-queue.js";
@@ -60,18 +69,17 @@ export { SamplingBridge } from "./src/sampling/sampling-bridge.js";
 
 // Type exports
 export type {
-  ConcurrentServerOptions,
   HttpRateLimitContext,
   HttpRateLimitOptions,
   HttpServerInstance,
   // HTTP Server types
   HttpServerOptions,
+  McpAppOptions,
   // MCP Apps types (SEP-1865)
   MCPResource,
   MCPTool,
   MCPToolMeta,
   McpUiToolMeta,
-  ToolAnnotations,
   QueueMetrics,
   RateLimitContext,
   RateLimitOptions,
@@ -81,23 +89,35 @@ export type {
   SamplingParams,
   SamplingResult,
   StructuredToolResult,
+  ToolAnnotations,
   ToolErrorMapper,
   ToolHandler,
 } from "./src/types.js";
 
+/**
+ * @deprecated Use {@link McpAppOptions} instead. `ConcurrentServerOptions`
+ * is kept as a re-export for backwards compatibility and will be removed
+ * in v1.0.
+ */
+export type { McpAppOptions as ConcurrentServerOptions } from "./src/types.js";
+
 // MCP Apps constants & viewer utilities
 export { MCP_APP_MIME_TYPE } from "./src/types.js";
 export type {
   RegisterViewersConfig,
   RegisterViewersSummary,
-} from "./src/concurrent-server.js";
+} from "./src/mcp-app.js";
 export {
-  resolveViewerDistPath,
   discoverViewers,
+  resolveViewerDistPath,
 } from "./src/ui/viewer-utils.js";
 
 // MCP Compose — UI composition helpers (re-exported from @casys/mcp-compose)
-export { composeEvents, COMPOSE_EVENT_METHOD, uiMeta } from "@casys/mcp-compose/sdk";
+export {
+  COMPOSE_EVENT_METHOD,
+  composeEvents,
+  uiMeta,
+} from "@casys/mcp-compose/sdk";
 export type {
   ComposeEventHandler,
   ComposeEventPayload,
@@ -134,6 +154,14 @@ export type {
   ProtectedResourceMetadata,
 } from "./src/auth/mod.js";
 
+// Auth - Multi-tenant resolution
+export { createMultiTenantMiddleware } from "./src/auth/mod.js";
+export type {
+  MultiTenantMiddlewareOptions,
+  TenantResolution,
+  TenantResolver,
+} from "./src/auth/mod.js";
+
 // Auth - JWT Provider + Presets
 export { JwtAuthProvider } from "./src/auth/mod.js";
 export type { JwtAuthProviderOptions } from "./src/auth/mod.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@casys/mcp-server",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Production-ready MCP server framework with concurrency control, auth, and observability",
   "type": "module",
   "main": "mod.ts",

package/src/auth/mod.ts

@@ -1,5 +1,5 @@
 /**
- * Auth module for ConcurrentMCPServer.
+ * Auth module for McpApp.
  *
  * @module lib/server/auth
  */
@@ -26,6 +26,14 @@ export {
 // Scope enforcement
 export { createScopeMiddleware } from "./scope-middleware.js";
 
+// Multi-tenant resolution (tenant enforcement on top of auth)
+export { createMultiTenantMiddleware } from "./multi-tenant-middleware.js";
+export type {
+  MultiTenantMiddlewareOptions,
+  TenantResolution,
+  TenantResolver,
+} from "./multi-tenant-middleware.js";
+
 // JWT Provider
 export { JwtAuthProvider } from "./jwt-provider.js";
 export type { JwtAuthProviderOptions } from "./jwt-provider.js";

package/src/auth/multi-tenant-middleware.ts

@@ -0,0 +1,236 @@
+/**
+ * Multi-tenant resolution middleware for MCP servers.
+ *
+ * Extends the auth pipeline with tenant identification and validation.
+ * Consumers provide a {@link TenantResolver} that knows how to map an
+ * authenticated request to a tenant identifier — typically by combining
+ * the HTTP Host header (subdomain-based tenancy) with a custom JWT claim.
+ *
+ * The resolved `tenantId` is injected into `ctx.authInfo.tenantId` so
+ * downstream middlewares and tool handlers can scope data access.
+ *
+ * This middleware is **optional**. Single-tenant servers do not need it.
+ * When used, it MUST be placed AFTER the auth middleware (which populates
+ * `ctx.authInfo`) and BEFORE the scope middleware and tool handlers.
+ *
+ * @example Pipeline wiring
+ * ```typescript
+ * server.use(createAuthMiddleware(authProvider));
+ * server.use(createMultiTenantMiddleware(new MyTenantResolver(), {
+ *   onRejection: (ctx, reason) => auditLog.warn("tenant_reject", { reason }),
+ * }));
+ * server.use(createScopeMiddleware(toolScopes));
+ * ```
+ *
+ * @module lib/server/auth/multi-tenant-middleware
+ */
+
+import type { Middleware, MiddlewareContext } from "../middleware/types.js";
+import type { AuthInfo } from "./types.js";
+import { AuthError } from "./middleware.js";
+
+/**
+ * Result of a tenant resolution attempt.
+ *
+ * Use `{ ok: true, tenantId }` when the request is valid and the tenant
+ * has been identified. Use `{ ok: false, reason }` to reject the request
+ * (the reason is passed to `onRejection` for logging but NEVER returned
+ * to the client, to avoid leaking tenant topology).
+ */
+export type TenantResolution =
+  | { ok: true; tenantId: string }
+  | { ok: false; reason: string };
+
+/**
+ * Resolves and validates the tenant for an incoming MCP request.
+ *
+ * Implementations typically:
+ *   1. Read a tenant hint from the request (subdomain, path, header, …)
+ *   2. Read the authoritative tenant from `ctx.authInfo.claims`
+ *   3. Validate they match
+ *   4. Return the tenant identifier, or a rejection reason
+ *
+ * @example Subdomain + JWT claim matching
+ * ```typescript
+ * class SubdomainTenantResolver implements TenantResolver {
+ *   async resolve(ctx: MiddlewareContext): Promise<TenantResolution> {
+ *     const host = ctx.request!.headers.get("host") ?? "";
+ *     const subdomain = host.split(".")[0];
+ *
+ *     const authInfo = ctx.authInfo as AuthInfo;
+ *     const claim = authInfo.claims?.["urn:my-app:tenant_id"];
+ *
+ *     if (typeof claim !== "string") {
+ *       return { ok: false, reason: "tenant_id claim missing or not a string" };
+ *     }
+ *     if (claim !== subdomain) {
+ *       return { ok: false, reason: `subdomain=${subdomain} claim=${claim}` };
+ *     }
+ *     return { ok: true, tenantId: subdomain };
+ *   }
+ * }
+ * ```
+ */
+export interface TenantResolver {
+  /**
+   * Resolve the tenant for this request.
+   *
+   * @param ctx - Middleware context with `ctx.request` and `ctx.authInfo` populated
+   * @returns A successful resolution with the tenant id, or a rejection with a reason
+   * @throws May throw — throwing is treated identically to returning `{ ok: false }`
+   */
+  resolve(ctx: MiddlewareContext): Promise<TenantResolution>;
+}
+
+/**
+ * Options for {@link createMultiTenantMiddleware}.
+ */
+export interface MultiTenantMiddlewareOptions {
+  /**
+   * Called whenever a request is rejected — either because the resolver
+   * returned `{ ok: false }`, threw an exception, or returned an empty
+   * `tenantId`.
+   *
+   * Typical use: write an audit log entry for compliance / forensics.
+   * The `reason` string may contain sensitive details (tenant ids, claim
+   * values) — log it server-side but never expose it to clients.
+   *
+   * Awaited before the client receives the 401 response, so audit writes
+   * are guaranteed to land before the error is observable. Keep it fast —
+   * slow callbacks delay the rejection.
+   *
+   * If this hook itself throws, the exception is **caught and logged to
+   * stderr** but NOT rethrown — the client still receives the standard
+   * generic `invalid_token` AuthError. A crashing audit hook must never
+   * change client-visible behaviour, otherwise a buggy audit path becomes
+   * an observable oracle for attackers probing tenant topology.
+   */
+  onRejection?: (
+    ctx: MiddlewareContext,
+    reason: string,
+  ) => void | Promise<void>;
+}
+
+/**
+ * Create a tenant resolution middleware.
+ *
+ * Pipeline behaviour:
+ *
+ * - **STDIO transport** (no `ctx.request`) → pass through unchanged. STDIO
+ *   is a local trusted transport with no meaningful notion of tenant.
+ *
+ * - **HTTP without `ctx.authInfo`** → throws a configuration error. This
+ *   indicates the auth middleware is missing from the pipeline. Fail fast
+ *   rather than silently skipping tenant enforcement.
+ *
+ * - **HTTP with `ctx.authInfo`** → calls `resolver.resolve(ctx)`:
+ *   - On success with a non-empty `tenantId`: copies `authInfo`, injects
+ *     `tenantId`, re-freezes, continues.
+ *   - On rejection (`ok: false`, thrown, or empty `tenantId`): calls
+ *     `onRejection`, then throws {@link AuthError}`("invalid_token")` —
+ *     the client sees a generic 401 with no tenant details leaked.
+ *
+ * @param resolver - Implementation that maps requests to tenant ids
+ * @param options - Optional hooks (notably `onRejection` for audit logging)
+ */
+export function createMultiTenantMiddleware(
+  resolver: TenantResolver,
+  options: MultiTenantMiddlewareOptions = {},
+): Middleware {
+  return async (ctx, next) => {
+    // STDIO transport: no request, tenant routing does not apply
+    if (!ctx.request) {
+      return next();
+    }
+
+    // Auth middleware MUST have populated authInfo before we run.
+    // MiddlewareContext is indexed as `[key: string]: unknown` for extensibility,
+    // so every auth-aware middleware in this lib casts to the concrete type —
+    // matches the convention in middleware.ts and scope-middleware.ts.
+    const authInfo = ctx.authInfo as AuthInfo | undefined;
+    if (!authInfo) {
+      throw new Error(
+        "[MultiTenantMiddleware] ctx.authInfo is not set. Ensure auth " +
+          "middleware is placed BEFORE multi-tenant middleware in the pipeline.",
+      );
+    }
+
+    // Resolve the tenant — any failure path collapses to a generic 401
+    let resolution: TenantResolution;
+    try {
+      resolution = await resolver.resolve(ctx);
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      throw await rejectWithAudit(ctx, reason, options.onRejection);
+    }
+
+    if (!resolution.ok) {
+      throw await rejectWithAudit(ctx, resolution.reason, options.onRejection);
+    }
+
+    // Defense-in-depth: reject empty string tenantId even when the resolver
+    // reports success. Some consumers use truthy guards (`if (tenantId)`),
+    // and an empty string would slip past them without being noticed.
+    if (!resolution.tenantId) {
+      throw await rejectWithAudit(
+        ctx,
+        "resolver returned empty tenantId",
+        options.onRejection,
+      );
+    }
+
+    // Re-freeze authInfo with tenantId injected. Two reasons for the re-freeze:
+    //   1. Preserves the immutability guarantee downstream middleware and
+    //      tool handlers rely on — they must never observe a mutable tenantId.
+    //   2. The original authInfo is already frozen by the auth middleware,
+    //      so in-place mutation is impossible anyway. We must spread-copy.
+    ctx.authInfo = Object.freeze({
+      ...authInfo,
+      tenantId: resolution.tenantId,
+    });
+
+    return next();
+  };
+}
+
+/**
+ * Run the audit hook (if any) and return a generic `invalid_token` AuthError.
+ *
+ * The hook is intentionally shielded with try/catch: a crashing audit hook
+ * must NEVER change the client-visible response. If the hook throws, the
+ * audit is lost (logged to stderr as a last resort) but the client still
+ * receives the standard 401 AuthError — preserving the non-leak guarantee.
+ *
+ * @internal
+ */
+async function rejectWithAudit(
+  ctx: MiddlewareContext,
+  reason: string,
+  onRejection: MultiTenantMiddlewareOptions["onRejection"],
+): Promise<AuthError> {
+  if (onRejection) {
+    try {
+      await onRejection(ctx, reason);
+    } catch (hookErr) {
+      // Last-resort logging: stderr is the only safe channel here — we must
+      // not rethrow (would defeat the non-leak guarantee) and we must not
+      // silently drop (would leave no trace of an audit failure).
+      console.error(
+        "[MultiTenantMiddleware] onRejection hook threw; audit entry lost:",
+        hookErr,
+      );
+    }
+  }
+  return buildAuthError(ctx);
+}
+
+/**
+ * Build a generic `invalid_token` AuthError using the resource metadata URL
+ * already set by the upstream auth middleware. If the URL is missing (should
+ * not happen in a well-formed pipeline), fall back to an empty string — the
+ * AuthError still produces a valid 401 response.
+ */
+function buildAuthError(ctx: MiddlewareContext): AuthError {
+  const metadataUrl = (ctx.resourceMetadataUrl as string | undefined) ?? "";
+  return new AuthError("invalid_token", metadataUrl);
+}

package/src/auth/types.ts

@@ -1,5 +1,5 @@
 /**
- * Authentication types for ConcurrentMCPServer.
+ * Authentication types for McpApp.
  *
  * Types follow RFC 9728 (OAuth Protected Resource Metadata)
  * and MCP Auth spec (draft 2025-11-25).
@@ -26,6 +26,17 @@ export interface AuthInfo {
 
   /** Token expiration timestamp (Unix epoch seconds) */
   expiresAt?: number;
+
+  /**
+   * Tenant identifier for multi-tenant servers.
+   *
+   * Populated by `createMultiTenantMiddleware` when a `TenantResolver`
+   * is configured. Undefined on single-tenant servers.
+   *
+   * Tool handlers in multi-tenant servers should read this (never trust
+   * raw JWT claims directly) to scope data access to the current tenant.
+   */
+  tenantId?: string;
 }
 
 /**

package/src/inspector/launcher.ts

@@ -54,8 +54,12 @@ export async function launchInspector(
     CLIENT_PORT: String(port),
   };
 
-  console.error(`[mcp-inspector] Starting inspector on http://localhost:${port}`);
-  console.error(`[mcp-inspector] Server: ${serverCommand} ${filteredArgs.join(" ")}`);
+  console.error(
+    `[mcp-inspector] Starting inspector on http://localhost:${port}`,
+  );
+  console.error(
+    `[mcp-inspector] Server: ${serverCommand} ${filteredArgs.join(" ")}`,
+  );
 
   // Use npx to run the inspector
   const command = new Deno.Command("npx", {

package/src/{concurrent-server.ts → mcp-app.ts}

@@ -1,21 +1,23 @@
 /**
- * Concurrent MCP Server Framework
+ * McpApp — Hono-style framework for MCP servers
  *
  * High-performance MCP server with built-in concurrency control,
  * backpressure, and optional sampling support.
  *
  * Wraps the official @modelcontextprotocol/sdk with production-ready
- * concurrency features.
+ * middleware, auth, and observability features.
  *
- * @module lib/server/concurrent-server
+ * @module lib/server/mcp-app
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
+  type CallToolRequest,
   CallToolRequestSchema,
-  ListToolsRequestSchema,
   ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  type ReadResourceRequest,
   ReadResourceRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import { Hono } from "hono";
@@ -45,9 +47,10 @@ import { createScopeMiddleware } from "./auth/scope-middleware.js";
 import { createAuthProviderFromConfig, loadAuthConfig } from "./auth/config.js";
 import type { AuthProvider } from "./auth/provider.js";
 import type {
-  ConcurrentServerOptions,
+  FetchHandler,
   HttpRateLimitContext,
   HttpServerOptions,
+  McpAppOptions,
   MCPResource,
   MCPTool,
   QueueMetrics,
@@ -57,7 +60,7 @@ import type {
   ToolHandler,
 } from "./types.js";
 import { MCP_APP_MIME_TYPE, MCP_APP_URI_SCHEME } from "./types.js";
-import { resolveViewerDistPath, discoverViewers } from "./ui/viewer-utils.js";
+import { discoverViewers, resolveViewerDistPath } from "./ui/viewer-utils.js";
 import type { DirEntry, DiscoverViewersFS } from "./ui/viewer-utils.js";
 import { buildCspHeader, injectCspMetaTag } from "./security/csp.js";
 import { ServerMetrics } from "./observability/metrics.js";
@@ -157,7 +160,7 @@ async function readBodyWithLimit(
 }
 
 /**
- * ConcurrentMCPServer provides a high-performance MCP server
+ * McpApp provides a high-performance MCP server
  *
  * Features:
  * - Wraps official @modelcontextprotocol/sdk
@@ -169,7 +172,7 @@ async function readBodyWithLimit(
  *
  * @example
  * ```typescript
- * const server = new ConcurrentMCPServer({
+ * const server = new McpApp({
  *   name: "my-server",
  *   version: "1.0.0",
  *   maxConcurrent: 5,
@@ -180,7 +183,7 @@ async function readBodyWithLimit(
  * await server.start();
  * ```
  */
-export class ConcurrentMCPServer {
+export class McpApp {
   private mcpServer: McpServer;
   private requestQueue: RequestQueue;
   private rateLimiter: RateLimiter | null = null;
@@ -188,7 +191,7 @@ export class ConcurrentMCPServer {
   private samplingBridge: SamplingBridge | null = null;
   private tools = new Map<string, ToolWithHandler>();
   private resources = new Map<string, RegisteredResourceInfo>();
-  private options: ConcurrentServerOptions;
+  private options: McpAppOptions;
   private started = false;
   private resourceHandlersInstalled = false;
 
@@ -222,7 +225,7 @@ export class ConcurrentMCPServer {
     windowMs: 60_000,
   });
 
-  constructor(options: ConcurrentServerOptions) {
+  constructor(options: McpAppOptions) {
     this.options = options;
 
     // Create SDK MCP server
@@ -300,26 +303,29 @@ export class ConcurrentMCPServer {
     });
 
     // resources/read — serve resource content by URI
-    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-      const uri = request.params.uri;
-      const info = this.resources.get(uri);
-      if (!info) {
-        throw new Error(`Resource not found: ${uri}`);
-      }
+    server.setRequestHandler(
+      ReadResourceRequestSchema,
+      async (request: ReadResourceRequest) => {
+        const uri = request.params.uri;
+        const info = this.resources.get(uri);
+        if (!info) {
+          throw new Error(`Resource not found: ${uri}`);
+        }
 
-      try {
-        const content = await info.handler(new URL(uri));
-        const finalContent = this.applyResourceCsp(content);
-        return { contents: [finalContent] };
-      } catch (error) {
-        this.log(
-          `[ERROR] Resource handler failed for ${uri}: ${
-            error instanceof Error ? error.message : String(error)
-          }`,
-        );
-        throw error;
-      }
-    });
+        try {
+          const content = await info.handler(new URL(uri));
+          const finalContent = this.applyResourceCsp(content);
+          return { contents: [finalContent] };
+        } catch (error) {
+          this.log(
+            `[ERROR] Resource handler failed for ${uri}: ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+          );
+          throw error;
+        }
+      },
+    );
 
     this.resourceHandlersInstalled = true;
     this.log("Resources capability pre-declared (expectResources: true)");
@@ -342,20 +348,24 @@ export class ConcurrentMCPServer {
     });
 
     // tools/call handler (delegates to middleware pipeline)
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
-      const toolName = request.params.name;
-      const args = request.params.arguments || {};
+    server.setRequestHandler(
+      CallToolRequestSchema,
+      async (request: CallToolRequest) => {
+        const toolName = request.params.name;
+        const args = request.params.arguments || {};
 
-      let result: unknown;
-      try {
-        result = await this.executeToolCall(toolName, args);
-      } catch (error) {
-        return this.handleToolError(error, toolName);
-      }
+        let result: unknown;
+        try {
+          result = await this.executeToolCall(toolName, args);
+        } catch (error) {
+          return this.handleToolError(error, toolName);
+        }
 
-      // Serialization errors are framework bugs, not tool errors — let them propagate
-      return this.buildToolCallResult(toolName, result);
-    });
+        // Serialization errors are framework bugs, not tool errors —
+        // let them propagate
+        return this.buildToolCallResult(toolName, result);
+      },
+    );
   }
 
   /**
@@ -370,7 +380,7 @@ export class ConcurrentMCPServer {
   ): void {
     if (this.started) {
       throw new Error(
-        "[ConcurrentMCPServer] Cannot register tools after server started. " +
+        "[McpApp] Cannot register tools after server started. " +
           "Call registerTools() before start() or startHttp().",
       );
     }
@@ -403,7 +413,7 @@ export class ConcurrentMCPServer {
   registerTool(tool: MCPTool, handler: ToolHandler): void {
     if (this.started) {
       throw new Error(
-        "[ConcurrentMCPServer] Cannot register tools after server started. " +
+        "[McpApp] Cannot register tools after server started. " +
           "Call registerTool() before start() or startHttp().",
       );
     }
@@ -481,7 +491,9 @@ export class ConcurrentMCPServer {
   unregisterTool(toolName: string): boolean {
     const deleted = this.tools.delete(toolName);
     if (deleted) {
-      this.log(`Unregistered tool: ${toolName} (remaining: ${this.tools.size})`);
+      this.log(
+        `Unregistered tool: ${toolName} (remaining: ${this.tools.size})`,
+      );
     }
     return deleted;
   }
@@ -513,7 +525,7 @@ export class ConcurrentMCPServer {
   use(middleware: Middleware): this {
     if (this.started) {
       throw new Error(
-        "[ConcurrentMCPServer] Cannot add middleware after server started. " +
+        "[McpApp] Cannot add middleware after server started. " +
           "Call use() before start() or startHttp().",
       );
     }
@@ -593,7 +605,7 @@ export class ConcurrentMCPServer {
   ): Promise<MiddlewareResult> {
     if (!this.middlewareRunner) {
       throw new Error(
-        "[ConcurrentMCPServer] Pipeline not built. Call start() or startHttp() first.",
+        "[McpApp] Pipeline not built. Call start() or startHttp() first.",
       );
     }
 
@@ -698,7 +710,7 @@ export class ConcurrentMCPServer {
     // Check for duplicate
     if (this.resources.has(resource.uri)) {
       throw new Error(
-        `[ConcurrentMCPServer] Resource already registered: ${resource.uri}`,
+        `[McpApp] Resource already registered: ${resource.uri}`,
       );
     }
 
@@ -760,7 +772,7 @@ export class ConcurrentMCPServer {
 
     if (missingHandlers.length > 0) {
       throw new Error(
-        `[ConcurrentMCPServer] Missing handlers for resources:\n` +
+        `[McpApp] Missing handlers for resources:\n` +
           missingHandlers.map((uri) => `  - ${uri}`).join("\n"),
       );
     }
@@ -775,7 +787,7 @@ export class ConcurrentMCPServer {
 
     if (duplicateUris.length > 0) {
       throw new Error(
-        `[ConcurrentMCPServer] Resources already registered:\n` +
+        `[McpApp] Resources already registered:\n` +
           duplicateUris.map((uri) => `  - ${uri}`).join("\n"),
       );
     }
@@ -786,7 +798,7 @@ export class ConcurrentMCPServer {
       if (!handler) {
         // Should never happen after validation, but defensive check
         throw new Error(
-          `[ConcurrentMCPServer] Handler disappeared for ${resource.uri}`,
+          `[McpApp] Handler disappeared for ${resource.uri}`,
         );
       }
       this.registerResource(resource, handler);
@@ -808,7 +820,9 @@ export class ConcurrentMCPServer {
    */
   registerViewers(config: RegisterViewersConfig): RegisterViewersSummary {
     if (!config.prefix) {
-      throw new Error("[ConcurrentMCPServer] registerViewers: prefix is required");
+      throw new Error(
+        "[McpApp] registerViewers: prefix is required",
+      );
     }
 
     // Resolve viewer list: explicit or auto-discovered
@@ -826,7 +840,11 @@ export class ConcurrentMCPServer {
     const skipped: string[] = [];
 
     for (const viewerName of viewerNames) {
-      const distPath = resolveViewerDistPath(config.moduleUrl, viewerName, config.exists);
+      const distPath = resolveViewerDistPath(
+        config.moduleUrl,
+        viewerName,
+        config.exists,
+      );
 
       if (!distPath) {
         this.log(
@@ -856,7 +874,9 @@ export class ConcurrentMCPServer {
             text: html,
           };
           if (config.csp) {
-            (content as unknown as Record<string, unknown>)._meta = { ui: { csp: config.csp } };
+            (content as unknown as Record<string, unknown>)._meta = {
+              ui: { csp: config.csp },
+            };
           }
           return content;
         },
@@ -866,7 +886,9 @@ export class ConcurrentMCPServer {
     }
 
     if (registered.length > 0) {
-      this.log(`Registered ${registered.length} viewer(s): ${registered.join(", ")}`);
+      this.log(
+        `Registered ${registered.length} viewer(s): ${registered.join(", ")}`,
+      );
     }
 
     return { registered, skipped };
@@ -911,8 +933,8 @@ export class ConcurrentMCPServer {
    */
   private cleanupSessions(): void {
     const now = Date.now();
-    const ttlWithGrace = ConcurrentMCPServer.SESSION_TTL_MS +
-      ConcurrentMCPServer.SESSION_GRACE_PERIOD_MS;
+    const ttlWithGrace = McpApp.SESSION_TTL_MS +
+      McpApp.SESSION_GRACE_PERIOD_MS;
     let cleaned = 0;
     for (const [sessionId, session] of this.sessions) {
       if (now - session.lastActivity > ttlWithGrace) {
@@ -998,7 +1020,7 @@ export class ConcurrentMCPServer {
    *
    * @example
    * ```typescript
-   * const server = new ConcurrentMCPServer({ name: "my-server", version: "1.0.0" });
+   * const server = new McpApp({ name: "my-server", version: "1.0.0" });
    * server.registerTools(tools, handlers);
    * server.registerResource(resource, handler);
    *
@@ -1038,7 +1060,7 @@ export class ConcurrentMCPServer {
     const requireAuth = options.requireAuth ?? false;
     if (requireAuth && !this.authProvider) {
       throw new Error(
-        "[ConcurrentMCPServer] HTTP auth is required (requireAuth=true) but no auth provider is configured.",
+        "[McpApp] HTTP auth is required (requireAuth=true) but no auth provider is configured.",
       );
     }
     if (!this.authProvider && !requireAuth) {
@@ -1411,9 +1433,9 @@ export class ConcurrentMCPServer {
           }
 
           // Guard against session exhaustion
-          if (this.sessions.size >= ConcurrentMCPServer.MAX_SESSIONS) {
+          if (this.sessions.size >= McpApp.MAX_SESSIONS) {
             this.cleanupSessions();
-            if (this.sessions.size >= ConcurrentMCPServer.MAX_SESSIONS) {
+            if (this.sessions.size >= McpApp.MAX_SESSIONS) {
               return c.json({
                 jsonrpc: "2.0",
                 id,
@@ -1442,7 +1464,9 @@ export class ConcurrentMCPServer {
                   name: this.options.name,
                   version: this.options.version,
                 },
-                ...(this.options.instructions ? { instructions: this.options.instructions } : {}),
+                ...(this.options.instructions
+                  ? { instructions: this.options.instructions }
+                  : {}),
               },
             }),
             {
@@ -1513,7 +1537,9 @@ export class ConcurrentMCPServer {
             } catch (rethrown) {
               this.log(
                 `Error executing tool ${toolName}: ${
-                  rethrown instanceof Error ? rethrown.message : String(rethrown)
+                  rethrown instanceof Error
+                    ? rethrown.message
+                    : String(rethrown)
                 }`,
               );
               const errorMessage = rethrown instanceof Error
@@ -1663,6 +1689,37 @@ export class ConcurrentMCPServer {
     // deno-lint-ignore no-explicit-any
     app.post("/", handleMcpPost as any);
 
+    // Embedded mode: skip serve(), surface the Hono fetch handler to the
+    // caller and let them mount it inside their own framework (Fresh, Hono,
+    // Express, etc.). The session cleanup timer + post-init still runs so
+    // SSE clients and sessions are managed identically to the serve() path.
+    if (options.embedded) {
+      if (!options.embeddedHandlerCallback) {
+        throw new Error(
+          "[McpApp] embedded=true requires embeddedHandlerCallback",
+        );
+      }
+      // deno-lint-ignore no-explicit-any
+      options.embeddedHandlerCallback(app.fetch as any);
+      this.started = true;
+      this.sessionCleanupTimer = setInterval(
+        () => this.cleanupSessions(),
+        McpApp.SESSION_CLEANUP_INTERVAL_MS,
+      );
+      unrefTimer(this.sessionCleanupTimer as unknown as number);
+      this.log(
+        `HTTP handler ready (embedded mode — no port bound, max concurrent: ${
+          this.options.maxConcurrent ?? 10
+        })`,
+      );
+      return {
+        shutdown: async () => {
+          await this.stop();
+        },
+        addr: { hostname: "embedded", port: 0 },
+      };
+    }
+
     // Start server
     this.httpServer = serve(
       {
@@ -1683,7 +1740,7 @@ export class ConcurrentMCPServer {
     // Start session cleanup timer (prevents unbounded memory growth)
     this.sessionCleanupTimer = setInterval(
       () => this.cleanupSessions(),
-      ConcurrentMCPServer.SESSION_CLEANUP_INTERVAL_MS,
+      McpApp.SESSION_CLEANUP_INTERVAL_MS,
     );
     // Don't block Deno from exiting because of cleanup timer
     unrefTimer(this.sessionCleanupTimer as unknown as number);
@@ -1714,6 +1771,67 @@ export class ConcurrentMCPServer {
     };
   }
 
+  /**
+   * Build the HTTP middleware stack and return its fetch handler without
+   * binding a port. Use this when you want to mount the MCP HTTP layer
+   * inside another HTTP framework (Fresh, Hono, Express, Cloudflare Workers,
+   * etc.) instead of giving up port ownership to {@link startHttp}.
+   *
+   * The returned handler accepts a Web Standard {@link Request} and returns
+   * a Web Standard {@link Response}. It exposes the same routes as
+   * {@link startHttp}: `POST /mcp`, `GET /mcp` (SSE), `GET /health`,
+   * `GET /metrics`, and `GET /.well-known/oauth-protected-resource`.
+   *
+   * Auth, multi-tenant middleware, scope checks, and rate limiting are all
+   * applied identically. The session cleanup timer and OTel hooks are
+   * started, so the server is fully live after this returns — just without
+   * its own listening socket.
+   *
+   * Multi-tenant SaaS pattern: cache one `McpApp` per tenant
+   * and call `getFetchHandler()` once per server, then dispatch each
+   * inbound request to the right cached handler from your framework's
+   * routing layer.
+   *
+   * @example
+   * ```typescript
+   * // In a Fresh route at routes/mcp/[...path].tsx
+   * const server = new McpApp({ name: "my-mcp", version: "1.0.0" });
+   * server.registerTools(tools, handlers);
+   * const handler = await server.getFetchHandler({
+   *   requireAuth: true,
+   *   auth: { provider: myAuthProvider },
+   * });
+   * // Later, in your route handler:
+   * return await handler(ctx.req);
+   * ```
+   *
+   * @param options - Same as {@link startHttp}, minus `port`/`hostname`/`onListen`.
+   * @returns A Web Standard fetch handler.
+   */
+  async getFetchHandler(
+    options: Omit<HttpServerOptions, "port" | "hostname" | "onListen"> = {},
+  ): Promise<FetchHandler> {
+    let captured: FetchHandler | null = null;
+    await this.startHttp({
+      // port/hostname are unused in embedded mode but the type requires them.
+      // Pass sentinel values that would never bind even if used.
+      port: 0,
+      ...options,
+      embedded: true,
+      embeddedHandlerCallback: (handler) => {
+        captured = handler;
+      },
+    });
+    if (!captured) {
+      // Defensive: startHttp should always invoke the callback synchronously
+      // before returning. If it didn't, something is structurally wrong.
+      throw new Error(
+        "[McpApp] getFetchHandler: embedded callback was not invoked",
+      );
+    }
+    return captured;
+  }
+
   /**
    * Send a JSON-RPC message to all SSE clients in a session
    * Used for server-initiated notifications and requests
@@ -1948,7 +2066,12 @@ export class ConcurrentMCPServer {
    * without re-wrapping. This supports proxy/gateway patterns.
    */
   // deno-lint-ignore no-explicit-any
-  private isPreformattedResult(result: unknown): result is { content: Array<{ type: string; text: string }>; _meta?: Record<string, unknown> } {
+  private isPreformattedResult(
+    result: unknown,
+  ): result is {
+    content: Array<{ type: string; text: string }>;
+    _meta?: Record<string, unknown>;
+  } {
     if (!result || typeof result !== "object") return false;
     const obj = result as Record<string, unknown>;
     return Array.isArray(obj.content) &&
@@ -2055,7 +2178,9 @@ export class ConcurrentMCPServer {
       } catch (mapperError) {
         this.log(
           `toolErrorMapper threw for tool ${toolName}: ${
-            mapperError instanceof Error ? mapperError.message : String(mapperError)
+            mapperError instanceof Error
+              ? mapperError.message
+              : String(mapperError)
           } (original error: ${
             error instanceof Error ? error.message : String(error)
           })`,
@@ -2114,7 +2239,11 @@ export interface RegisterViewersConfig {
   humanName?: (viewerName: string) => string;
   /** MCP Apps CSP — declares external domains the viewer needs (tiles, APIs, CDNs).
    *  Uses McpUiCsp from @casys/mcp-compose (resourceDomains, connectDomains). */
-  csp?: { resourceDomains?: string[]; connectDomains?: string[]; frameDomains?: string[] };
+  csp?: {
+    resourceDomains?: string[];
+    connectDomains?: string[];
+    frameDomains?: string[];
+  };
 }
 
 /** Summary returned by registerViewers() */

package/src/middleware/mod.ts

@@ -1,5 +1,5 @@
 /**
- * Middleware module for ConcurrentMCPServer.
+ * Middleware module for McpApp.
  *
  * @module lib/server/middleware
  */

package/src/middleware/rate-limit.ts

@@ -1,7 +1,7 @@
 /**
  * Rate limiting middleware.
  *
- * Extracted from ConcurrentMCPServer's inline rate limit logic.
+ * Extracted from McpApp's inline rate limit logic.
  *
  * @module lib/server/middleware/rate-limit
  */

package/src/middleware/types.ts

@@ -1,5 +1,5 @@
 /**
- * Middleware pipeline types for ConcurrentMCPServer.
+ * Middleware pipeline types for McpApp.
  *
  * Provides an onion-model middleware system (similar to Koa/Hono)
  * where each middleware wraps the next, enabling before/after logic.

package/src/observability/metrics.ts

@@ -2,7 +2,7 @@
  * Server Metrics Collector for @casys/mcp-server
  *
  * In-memory counters, histograms, and gauges with Prometheus text format export.
- * Designed to be embedded in ConcurrentMCPServer — no external dependencies.
+ * Designed to be embedded in McpApp — no external dependencies.
  *
  * @module lib/server/observability/metrics
  */

package/src/types.ts

@@ -45,9 +45,9 @@ export interface RateLimitContext {
 }
 
 /**
- * Configuration options for ConcurrentMCPServer
+ * Configuration options for McpApp
  */
-export interface ConcurrentServerOptions {
+export interface McpAppOptions {
   /** Server name (shown in MCP protocol) */
   name: string;
 
@@ -485,8 +485,15 @@ export interface HttpRateLimitOptions {
 /**
  * Options for starting an HTTP server
  */
+// Re-exported from the runtime port so consumers can import the canonical
+// fetch handler type from the same module as HttpServerOptions.
+export type { FetchHandler } from "./runtime/types.js";
+import type { FetchHandler } from "./runtime/types.js";
+
 export interface HttpServerOptions {
-  /** Port to listen on */
+  /**
+   * Port to listen on. Ignored when {@link embedded} is `true`.
+   */
   port: number;
 
   /** Hostname to bind to (default: "0.0.0.0") */
@@ -532,6 +539,27 @@ export interface HttpServerOptions {
    * @param info - Server address info
    */
   onListen?: (info: { hostname: string; port: number }) => void;
+
+  /**
+   * Embedded mode: skip binding a port and instead surface the Hono fetch
+   * handler via the {@link embeddedHandlerCallback} option. Used by
+   * {@link McpApp.getFetchHandler} so consumers (Fresh, Hono,
+   * Express, etc.) can mount the MCP HTTP stack inside their own server
+   * without giving up port ownership.
+   *
+   * When `true`, `port`, `hostname`, and `onListen` are ignored.
+   */
+  embedded?: boolean;
+
+  /**
+   * Receives the Hono fetch handler when running in embedded mode.
+   * Required when {@link embedded} is `true`. Called exactly once,
+   * synchronously, before `startHttp` returns.
+   *
+   * Most consumers should use {@link McpApp.getFetchHandler}
+   * instead of setting this directly.
+   */
+  embeddedHandlerCallback?: (handler: FetchHandler) => void;
 }
 
 /**

package/src/ui/viewer-utils.ts

@@ -8,7 +8,13 @@
  */
 
 /** Directories to skip during auto-discovery */
-const SKIP_DIRS = new Set(["shared", "dist", "node_modules", ".cache", ".vite"]);
+const SKIP_DIRS = new Set([
+  "shared",
+  "dist",
+  "node_modules",
+  ".cache",
+  ".vite",
+]);
 
 /**
  * Convert a file:// URL to a filesystem path.