stitchkit 0.43.0 → 0.44.0

package/llms-full.txt

@@ -27,7 +27,7 @@ bun add stitchkit zod
 
 `zod` is a required peer — schemas are the source of truth everywhere. Other
 peers are optional and pulled in only when you use the matching feature
-(`@modelcontextprotocol/sdk` for MCP, `ai` for agents, `socket.io*` for
+(`@modelcontextprotocol/server` for MCP servers, `ai` for agents, `socket.io*` for
 realtime, `@tanstack/react-query` + `react-query-kit` for React). See
 [deps](#dependencies) below.
 
@@ -141,9 +141,9 @@ map — feature → packages:
 | anything (validation) | `zod` |
 | `createServer` (Bun) | — (uses `Bun.serve`) |
 | `serveNode` (Node ≥ 22) | `srvx` (+ `@types/bun` dev) |
-| MCP tools (`stitchkit/tools`) | `@modelcontextprotocol/sdk` |
+| MCP / agent tools (`stitchkit/tools`) | `@modelcontextprotocol/server` `ai` |
+| MCP host/client tests | `@modelcontextprotocol/client` |
 | MCP Apps UI widgets | `@modelcontextprotocol/ext-apps` |
-| agent tools (`stitchkit/tools`) | `ai` |
 | React data layer (`stitchkit/react`) | `@tanstack/react-query` `react-query-kit` |
 | **Socket.IO server on Bun** | `socket.io` `@socket.io/bun-engine` |
 | **Socket.IO server on Node** | `socket.io` |
@@ -153,9 +153,22 @@ map — feature → packages:
 bun add socket.io @socket.io/bun-engine    # e.g. the Socket.IO server on Bun
 ```
 
-If an optional peer is missing, the feature that needs it fails with an
-actionable error naming the package and the install command — not a bare
-`Cannot find module`.
+Dynamic optional-peer adapters fail with an actionable error naming the package
+and install command. Static entrypoints such as `stitchkit/tools` fail during
+ESM resolution by naming the exact missing package; the feature-to-peer matrix
+below is the canonical install command.
+
+The combined tools entry owns MCP and AI-agent adapters, so install both runtime
+peers before importing `stitchkit/tools`:
+
+```bash
+bun add @modelcontextprotocol/server@^2 ai@^7
+```
+
+Browser, HTTP-client and React entrypoints remain usable without either MCP
+package. MCP hosts and client E2E additionally install
+`@modelcontextprotocol/client@^2`; Apps additionally install
+`@modelcontextprotocol/ext-apps`.
 
 ## Next
 
@@ -1546,10 +1559,16 @@ try {
     err.message  // 'Note not found'
     err.details  // structured details, if any
     err.hint     // optional hint
+    err.traceId  // x-request-id — correlate this failure with backend logs
   }
 }
 ```
 
+`traceId` is present when the server returned `x-request-id`. A network error,
+timeout or abort without an HTTP response cannot carry one. Cross-origin
+browser code can read it through Stitchkit's default CORS expose list; a custom
+`cors.exposeHeaders` policy must keep `x-request-id` exposed.
+
 The error model is shared with the server — see [Auth & errors](./auth-and-errors.md).
 
 ## Auth events
@@ -1798,27 +1817,28 @@ the invoker is created.
 
 ## MCP — `createMcpHandler`
 
-`createMcpHandler` builds a complete Streamable-HTTP MCP server as a single
-`Request → Response` handler. It owns the SDK server and transport lifecycle, so
-your app never imports `@modelcontextprotocol/sdk` itself.
+`createMcpHandler` builds a complete stateless Streamable-HTTP MCP endpoint on
+the official TypeScript SDK v2 server package. It owns server creation,
+protocol-era negotiation and shutdown; application code does not import the SDK
+to mount a normal endpoint.
 
 ```ts
-import { createMcpHandler } from 'stitchkit/tools'
+import { createMcpHandler, createMcpHttpRoute } from 'stitchkit/tools'
+import { createServer } from 'stitchkit/server'
 
-const handleMcp = createMcpHandler({
+const mcp = createMcpHandler({
   serverInfo: { name: 'my-app', version: '1.0.0' },
   auth: (req) => resolveApiKey(req),   // → an identity, or null for 401
   services: [usersService, catalogService],
 })
-```
-
-Mount the returned handler on a raw route — typically `/mcp`:
 
-```ts
 createServer({
   services,
-  rawRoutes: [{ method: 'ALL', path: '/mcp', handler: (req) => handleMcp(req) }],
+  rawRoutes: [createMcpHttpRoute({ path: '/mcp', handler: mcp })],
 })
+
+// During graceful shutdown:
+await mcp.close()
 ```
 
 ### `McpHandlerConfig`
@@ -1833,6 +1853,7 @@ createServer({
 | `selectSurface` | `(auth) => declaredKey` — required with `surfaces` |
 | `context` | `(auth) => {…}` — values merged into every tool handler's `ctx` |
 | `lifecycle` | `beforeHandle` / `afterHandle` — the tool-side auth gate (see below) |
+| `multiRound` | Typed MRTR state policy for guarded multi-round tool calls |
 | `hooks` | tool-call observability hooks — `afterToolCall` fires on every result |
 | `extend` | extra advertised arguments resolved into handler context |
 | `schemaValidation` | compatibility policy, typed-property guard and portable-format guard |
@@ -1845,7 +1866,10 @@ createServer({
 | `errorHint` | add a project-owned hint to failed tool results |
 | `onOutputStrip` | observe output keys removed by contract validation |
 | `protectedResource` | RFC 9728 metadata used by HTTP `401` responses |
-| `sessionMode` | `'stateless'` (default) or explicit `'stateful'` session/SSE continuity |
+| `legacy` | `'serve'` (default) or `'reject'` for pre-2026 clients |
+| `security` | optional Host/Origin allowlists at the Fetch boundary |
+| `onTransportRejected` | observe HTTP/protocol rejections without entering lifecycle or tool hooks |
+| `cache` | explicit operation cache hints; omitted means zero/private |
 
 Direct `services` / `runtimeTools` factories, `context`, `selectSurface` and
 `rawTools` receive the resolved identity, so a tenant can be shown only its own
@@ -1870,20 +1894,106 @@ const handleMcp = createMcpHandler({
 Every declared entry is schema-validated and prepared once when the handler is
 constructed. The selected immutable descriptors are shared; the SDK server,
 transport, auth-derived context, lifecycle runner and tool-call context are
-fresh for every stateless request (or every stateful session). Unknown keys
+fresh for every request. Unknown keys
 fail before the server connects. The registry never retains auth values.
 
-### Stateless by default; stateful only when required
-
-The default `sessionMode: 'stateless'` creates a fresh SDK server, transport,
-resolved auth/context and runner for each HTTP request. Static direct and finite
-registry schemas are still prepared once when the handler is constructed. There is no session
-map, event store, sweep timer or `Mcp-Session-Id`, so process replacement and
-load balancing cannot strand a client on an in-memory session.
+### Stateless transport and protocol eras
+
+Every request gets a fresh SDK server, resolved auth/context and tool-call
+runner. Static direct and finite registry schemas are still prepared once when
+the handler is constructed. There is no session map, event store,
+`Mcp-Session-Id` or resumable cross-request SSE state. Process replacement and
+load balancing therefore cannot strand a client on an in-memory session.
+
+The default `legacy: 'serve'` lets the official SDK negotiate either modern
+`2026-07-28` or the supported legacy stateless opening on this same endpoint.
+Set `legacy: 'reject'` when every host is modern. Legacy support is protocol
+translation inside the SDK, not a second Stitchkit transport or compatibility
+API. Stateful MCP and subscriptions are intentionally outside this layer.
+
+`createMcpHttpRoute` is the framework-owned raw-route adapter. It registers
+`ALL` because Streamable HTTP uses multiple HTTP methods, delegates only to
+`handler.fetch`, and leaves lifecycle ownership with the returned handler.
+
+By default, a present `Host` header must match the request URL and a present
+browser `Origin` must be same-origin. Non-browser hosts may omit `Origin`. Behind
+a trusted reverse proxy, reconstruct the public request URL before calling the
+handler or configure exact `security.allowedHosts` / `allowedOrigins`; never
+copy arbitrary forwarded headers into the trusted URL. If a browser calls MCP
+cross-origin, its HTTP server or gateway must also answer CORS preflight and
+expose the protocol headers. `onTransportRejected` is the audit boundary for
+HTTP/security rejections; it is deliberately separate from tool lifecycle and
+must not be used as authorization input.
+
+### Modern discovery, routing and cache hints
+
+Stitchkit forwards the negotiated protocol era and validated MCP request data
+to `RequestEvent.mcp`; untrusted routing headers never become application
+identity. The SDK validates `MCP-Protocol-Version`, JSON-RPC shape and routing
+metadata before lifecycle or tool handlers run. Framework-owned tool and
+resource registration preserves declaration order across HTTP and stdio. Tool
+manifests preserve mount order; `listToolNames` is a sorted diagnostics view.
+Consumer-owned raw SDK registrations are outside this guarantee.
+
+Caching is opt-in. `cache.operations` maps directly to SDK v2 operation cache
+hints, while each `McpResourceDef` may declare its own `cacheHint`. Omission
+means zero/private: neither a prepared surface nor a deterministic response is
+silently treated as public. Unbounded auth-selected surface factories are
+always forced to zero/private even when an operation policy is present; use a
+finite `surfaces` registry when identities share a provably immutable surface.
+Stitchkit never advertises list-change or subscription capabilities
+without an implementation.
+
+### Multi-round tool input (`input_required`)
+
+An MCP-only operation can require typed user input before its final side effect:
+
+```ts
+const DeleteConfirmationSchema = z.object({ confirmed: z.boolean() })
+
+deleteProject: {
+  method: 'DELETE',
+  path: '/projects/:id',
+  expose: ['MCP'],
+  input: DeleteProjectSchema,
+  output: DeleteProjectResultSchema,
+  mcp: {
+    inputRequired: [
+      {
+        key: 'confirmation',
+        schema: DeleteConfirmationSchema,
+        message: 'Confirm permanent deletion',
+      },
+      {
+        key: 'reason',
+        schema: z.object({ value: z.string().min(3) }),
+        message: 'Record the reason',
+      },
+    ],
+  },
+}
+```
 
-Opt into `sessionMode: 'stateful'` only when the client needs server-initiated
-messages, cross-request progress or resumable SSE. That mode issues a server
-session id and retains the bounded session/event stores until idle expiry.
+Each continuation accepts exactly the currently requested item. Only after the
+ordered sequence completes does the handler receive the exact aggregate as
+`ctx.mcpInput.confirmation` and `ctx.mcpInput.reason`; before then the framework
+returns `input_required` without calling it. Set
+`multiRound.serving.maxRounds` to the maximum declaration size you accept
+(default `10`); empty sequences, duplicate keys and overflow fail first. State
+is bound to principal, full operation identity, current round, accepted
+aggregate and canonical original-argument digest and is
+expiry-checked. Tampered, expired, cross-user or cross-tool state fails before
+the side effect. Output validation applies only to the final result.
+
+Every attempt re-runs auth/lifecycle and emits its own tool hooks; audit metadata
+contains the attempt's `mcp.outcome` and `mcp.round`. Stitchkit does not merge
+separate HTTP attempts into one logical trace. Parallel
+rounds have isolated context. HTTP/stdio modern hosts and the supported legacy
+stdio bridge may use this declaration; Agent, CLI and ordinary HTTP invocation
+remain single-round and unchanged. Hosts without the capability receive an
+ordinary unsupported result rather than a falsely advertised round. Signed
+state is tamper-resistant, not an exactly-once replay store; destructive
+handlers must still be idempotent where retries matter.
 
 ### Guarding tools — `lifecycle`
 
@@ -1942,9 +2052,9 @@ cannot become a tool. `schemaValidation.policy` decides what happens:
 startup assertion or a test.
 
 For a static `services` array, collection, schema conversion and every enabled
-validation guard run once when the handler is created. Each HTTP request or
-stateful session still receives a fresh `McpServer`, runner, context and native
-registration over that immutable prepared surface. A `services(auth)` factory
+validation guard run once when the handler is created. Each HTTP request still
+receives a fresh `McpServer`, runner, context and native registration over that
+immutable prepared surface. A `services(auth)` factory
 is deliberately prepared after resolving each identity because its tool set may
 change by tenant.
 
@@ -2051,11 +2161,14 @@ it can reach the local filesystem.
 ```ts
 import { createStdioMcpServer } from 'stitchkit/tools'
 
-await createStdioMcpServer({
+const stdio = await createStdioMcpServer({
   serverInfo: { name: 'my-app', version: '1.0.0' },
   auth: resolveIdentity(),          // resolved once at startup, not per request
   services: [usersService],
 })
+
+// During graceful shutdown:
+await stdio.close()
 ```
 
 A stdio server is a single process serving one client, so `auth` is a value (or
@@ -2063,6 +2176,11 @@ a promise of one) resolved once at startup — typically from an env var — rat
 than a per-request `(req) => …`. Keep all logging on **stderr**: stdout is the
 JSON-RPC channel.
 
+The default `legacy: 'serve'` negotiates the modern or supported legacy opening
+through the official stdio adapter. Use `legacy: 'reject'` for a modern-only
+binary. Each invocation builds a fresh server; the returned handle owns
+transport shutdown.
+
 Both transports build the server through the shared `buildMcpServer` — same
 contract/runtime pipeline, same surface selection, context, hooks, raw escape
 hatch and instructions.
@@ -2071,41 +2189,45 @@ hatch and instructions.
 
 A remote MCP server is connectable from Claude (Desktop / web "custom
 connector") only through the MCP authorization spec: OAuth 2.1 with PKCE, plus
-the discovery documents (RFC 9728 / 8414), Dynamic Client Registration
-(RFC 7591) and resource indicators (RFC 8707). A Bearer-only server returns a
+the discovery documents (RFC 9728 / 8414), Client ID Metadata Documents (CIMD)
+and resource indicators (RFC 8707). A Bearer-only server returns a
 bare `401` and the connector never establishes.
 
 stitchkit ships the OAuth **protocol mechanics**; the app supplies only
 **identity and storage**. Three pieces wire it together:
 
 ```ts
-import { createMcpHandler, mountOAuthProvider, oauthProtectedResourceRoute } from 'stitchkit/tools'
+import { createMcpHandler, createMcpHttpRoute, mountOAuthProvider, oauthProtectedResourceRoute } from 'stitchkit/tools'
 import { createServer } from 'stitchkit/server'
 
 const resource = 'https://api.example.com/mcp'
 const issuer = 'https://api.example.com'
 
 // 1. Resource server — the 401 now points at the metadata.
-const handleMcp = createMcpHandler({
+const mcp = createMcpHandler({
   serverInfo: { name: 'my-app', version: '1.0.0' },
   auth: resolveOAuthToken,        // validate the Bearer JWT (verifyJwt + audience)
   services,
   protectedResource: { resource, authorizationServers: [issuer] },
 })
 
-// 2. Authorization server — DCR, /authorize (PKCE), /token.
+// 2. Authorization server — CIMD, /authorize (PKCE), /token.
 const oauthRoutes = mountOAuthProvider({
   issuer,
   resource,
   signingSecret: env.OAUTH_SECRET,
-  clients, codes, refreshTokens,  // your stores (DB or in-memory)
-  authorizeUser,                  // your login + consent → { userId } | Response
+  clientRegistration: {
+    preRegistered: { get: getFirstPartyClient },
+    // CIMD is enabled with secure defaults; DCR remains disabled.
+  },
+  codes, refreshTokens,           // your stores (DB or in-memory)
+  authorizeUser,                  // → { userId, approvedScopes } | Response
 })
 
 createServer({
   services,
   rawRoutes: [
-    { method: 'ALL', path: '/mcp', handler: (req) => handleMcp(req) },
+    createMcpHttpRoute({ path: '/mcp', handler: mcp }),
     oauthProtectedResourceRoute({ resource, authorizationServers: [issuer] }),
     ...oauthRoutes,
   ],
@@ -2116,11 +2238,27 @@ Access tokens are signed HS256 JWTs (`signJwt`) whose `aud` is the resource and
 whose `iss` is the issuer — validate both in `auth` with
 `verifyJwt(token, secret, { audience: resource, issuer })`. `authorizeUser` is
 where the app authenticates the user (reuse an existing session) and records
-consent; return `{ userId }` to issue a code, or a `Response` to redirect the
-browser to a login page first. The AS and resource server can co-locate or live
+consent; return `{ userId, approvedScopes }`, where approved scopes are a subset
+of the requested/supported values, or a `Response` to redirect the browser to a
+login page first. The AS and resource server can co-locate or live
 on separate origins. See
 [ADR 0015](../decisions/0015-oauth-resource-server.md).
 
+Client resolution is deterministic: exact pre-registered client, then an HTTPS
+URL client id resolved as CIMD, then explicitly enabled DCR. CIMD is on by
+default; DCR is off unless `clientRegistration.dcr` supplies both `register` and
+`get`. A CIMD-only deployment therefore exposes neither `/register` nor a
+`registration_endpoint`. The metadata document must declare a `client_id` that
+exactly equals its URL, explicit redirect URIs and
+`token_endpoint_auth_method: 'none'`.
+
+The production fetcher rejects credentials, fragments, non-HTTPS URLs and
+private/reserved targets. Every redirect is DNS-resolved and IP-pinned again;
+timeouts, redirect count and body size are bounded. Its bounded cache respects
+`Cache-Control` (including `no-store`/`no-cache`), `Age`, `Expires`, `ETag` and
+`Last-Modified`, coalesces concurrent misses and reports sanitized cache events;
+invalid or unavailable identity receives only a short fail-closed cache entry.
+
 ### Authorization hardening (MCP 2026-07-28)
 
 - **`iss` on every authorization response (RFC 9207, SEP-2468).** Success *and*
@@ -2138,9 +2276,9 @@ on separate origins. See
   behaves exactly as before (loopback allowed); an unknown value is rejected
   rather than silently defaulted.
 
-> Dynamic Client Registration is **deprecated** in the 2026-07-28 spec in favour
-> of Client ID Metadata Documents (CIMD), with a ≥12-month window. DCR keeps
-> working and stays supported here; CIMD support is tracked separately.
+> Dynamic Client Registration is an explicit interoperability mode, not the
+> default. Enabling it changes public discovery and adds `/register`; keep it off
+> unless a client that cannot publish CIMD requires it.
 
 ## Proxying a remote API — `implementRemote`
 
@@ -2157,11 +2295,14 @@ const http = createHttpClient({
   headers: () => ({ Authorization: `Bearer ${apiKey}` }),
 })
 
-await createStdioMcpServer({
+const stdio = await createStdioMcpServer({
   serverInfo: { name: 'my-app', version: '1.0.0' },
   auth: null,
   services: contracts.map((c) => implementRemote(c, http)),
 })
+
+// During graceful shutdown:
+await stdio.close()
 ```
 
 This is how you ship a thin **local** MCP server for an API that already runs in
@@ -2175,9 +2316,16 @@ no duplicated business logic.
 
 ## Structured output
 
-When a contract endpoint declares an object `output`, its MCP tool registers
-that as the tool `outputSchema` and the result carries `structuredContent`
-alongside the text block — the structured payload an MCP App UI consumes.
+When a contract endpoint or runtime tool declares `output`, its MCP tool
+registers that exact schema as `outputSchema` and returns the validated value as
+`structuredContent` alongside a JSON text block. Every JSON root type is kept
+unchanged: object, array, string, number, boolean and `null`. Stitchkit does not
+wrap non-object values in `{ result }`; protocol-era adaptation belongs to the
+official SDK.
+
+A tool without an output contract advertises no `outputSchema` and returns no
+invented structured value. Its successful MCP result has an empty `content`
+list.
 
 ## AI agents — `mountAgent`
 
@@ -3342,8 +3490,9 @@ Use the exported `zodIssues(error)` to build the same structured list from a
 ### On the client
 
 The client parses that envelope back into an `ApiError` with the same `code`,
-`status`, `details` and `hint` — see [Typed client → ApiError](./client.md#apierror).
-The error round-trips: one model, server to client.
+`status`, `details` and `hint`, plus the response `x-request-id` as optional
+readonly `traceId` — see [Typed client → ApiError](./client.md#apierror). The
+error round-trips without adding correlation data to the response body.
 
 ### Stitch codes vs your codes
 
@@ -3701,7 +3850,8 @@ locally; you do not need to change `NODE_ENV` or deploy.
 Every response the stitchkit handler produces carries the resolved id as
 **`x-request-id`**. With `cors` configured it is in the default
 `Access-Control-Expose-Headers`, so a browser client can read it and quote it in
-a bug report. Note the deliberate asymmetry: inbound the id may arrive as
+a bug report. Stitchkit browser clients retain it as `ApiError.traceId` on
+response-backed failures. Note the deliberate asymmetry: inbound the id may arrive as
 `X-Trace-Id` *or* `X-Request-Id`; outbound there is one name and no alias.
 
 Log the same id from nginx and the two logs join on one key. `log_format` and
@@ -3751,8 +3901,25 @@ cross-origin `trace: true` client works out of the box. If you set a custom
 `cors.headers`, extend `DEFAULT_CORS_ALLOW_HEADERS` rather than replacing it, or
 the preflight will reject the trace header.
 
+MCP tools use the same context. On a modern HTTP or stdio `tools/call`, the
+official SDK exposes W3C propagation values from request `_meta`; Stitchkit
+continues a valid `_meta.traceparent` before validation, lifecycle and hooks.
+If MCP metadata omits `traceparent`, an HTTP call keeps its ambient HTTP trace
+and a stdio call starts a new root. If the key is present but malformed or
+all-zero, the call still runs under a fresh local trace instead of trusting the
+ambient one. This makes explicit MCP propagation authoritative without allowing
+invalid input to break the tool.
+
+Bounded `tracestate` and `baggage` are available through
+`getRequestContext()?.trace` for outbound propagation. Their contents are not
+copied into the standard `RequestEvent`; never use them for auth, RBAC, tenant
+selection or rate-limit identity. Every MRTR attempt reads its current request
+metadata, so callers that want one trace across rounds must propagate it on
+each request.
+
 > **Span ids live in the request context, not on `ctx`.** The handler `ctx`
-> carries a single `traceId`; the full `{ traceId, spanId, parentSpanId }` is on
+> carries a single `traceId`; the full
+> `{ traceId, spanId, parentSpanId, tracestate?, baggage? }` is on
 > the observability request context. To stamp `spanId` / `parentSpanId` into an
 > audit row read `getRequestContext()?.trace`, not `ctx.spanId`:
 >
@@ -4091,9 +4258,11 @@ an independently built Next.js frontend and Bun/Stitchkit API.
 
 ### MCP
 
-If the app exposes MCP tools, `createMcpHandler` is mounted as a raw route
-(`/mcp`). It needs the `@modelcontextprotocol/sdk` peer installed in production —
-it is optional only for apps that do not use MCP.
+If the app exposes MCP tools, mount `createMcpHandler` with
+`createMcpHttpRoute({ path: '/mcp', handler })` and close the handler during
+graceful shutdown. Production needs the `@modelcontextprotocol/server` v2 peer;
+apps without MCP do not. Only an MCP host or integration-test package needs
+`@modelcontextprotocol/client`.
 
 
 ==============================================================================
@@ -4362,6 +4531,174 @@ current one *up to* your target, and apply each snippet.
 
 ## Unreleased breaking migrations
 
+### MCP TypeScript SDK v2 and protocol `2026-07-28`
+
+This is a hard cut: there is one Stitchkit API and no v1 aliases. Applications
+that expose MCP install the split server package; applications that implement an
+MCP host or run client E2E install the split client package.
+
+```bash
+bun remove @modelcontextprotocol/sdk
+bun add @modelcontextprotocol/server@^2 ai@^7
+# MCP hosts and client-side E2E only:
+bun add -d @modelcontextprotocol/client@^2
+```
+
+Direct SDK imports move to the split packages too:
+
+```ts
+// before
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+
+// after
+import { McpServer } from '@modelcontextprotocol/server'
+```
+
+MCP Apps additionally install `@modelcontextprotocol/ext-apps`. That adapter may
+carry its own isolated v1-era transitive/peer relationship while the ecosystem
+finishes its cutover; it does not permit application code to import the removed
+monolithic SDK. Application-owned MCP server and client code uses the v2 split
+packages exclusively.
+
+```ts
+// before
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { createMcpHandler } from 'stitchkit/tools'
+
+const handleMcp = createMcpHandler({
+  serverInfo,
+  auth,
+  services,
+  sessionMode: 'stateless',
+})
+rawRoutes: [{ method: 'ALL', path: '/mcp', handler: handleMcp }]
+
+// after
+import { Client } from '@modelcontextprotocol/client'
+import { createMcpHandler, createMcpHttpRoute } from 'stitchkit/tools'
+
+const mcp = createMcpHandler({
+  serverInfo,
+  auth,
+  services,
+  legacy: 'serve',
+})
+rawRoutes: [createMcpHttpRoute({ path: '/mcp', handler: mcp })]
+// graceful shutdown: await mcp.close()
+```
+
+Keep the owned handle and close it from the same shutdown path as the HTTP
+server. A minimal runtime smoke should list tools before shutdown and prove the
+closed handler no longer serves requests:
+
+```ts
+const mcp = createMcpHandler(config)
+const route = createMcpHttpRoute({ path: '/mcp', handler: mcp })
+
+const beforeClose = await route.handler(listToolsRequest)
+if (!beforeClose.ok) throw new Error('MCP list-tools smoke failed')
+
+await mcp.close()
+```
+
+Remove `@modelcontextprotocol/sdk`, `sessionMode`, `McpSessionMode`, session
+stores and all `Mcp-Session-Id` handling. HTTP is always request-isolated and
+stateless. `legacy: 'serve'` (default) lets the official SDK negotiate supported
+pre-2026 stateless clients on the same endpoint; `legacy: 'reject'` makes it
+modern-only. This is not a stateful compatibility transport.
+
+The stdio helper now returns an owned lifecycle handle:
+
+```ts
+// before
+await createStdioMcpServer(config)
+
+// after
+const stdio = await createStdioMcpServer({ ...config, legacy: 'serve' })
+await stdio.close()
+```
+
+OAuth client registration is now one explicit policy object. CIMD is secure and
+enabled by default; DCR is disabled unless supplied:
+
+```ts
+// before
+mountOAuthProvider({ ...oauth, clients, codes, refreshTokens })
+
+// after
+mountOAuthProvider({
+  ...oauth,
+  clientRegistration: {
+    preRegistered: { get: clients.get },
+    // optional: dcr: { register: clients.register, get: clients.get }
+  },
+  codes,
+  refreshTokens,
+})
+```
+
+A URL client id must be HTTPS and serve a document whose `client_id` exactly
+matches that URL, with explicit `redirect_uris` and
+`token_endpoint_auth_method: 'none'`. Do not keep a consumer-side metadata
+fetcher or DCR fallback; Stitchkit owns SSRF-safe resolution and caching.
+
+Multi-round input is opt-in on the operation and does not change Agent, CLI or
+ordinary HTTP handlers:
+
+```ts
+const ConfirmationSchema = z.object({ confirmed: z.boolean() })
+
+mcp: {
+  inputRequired: [{
+    key: 'confirmation',
+    message: 'Confirm this action',
+    schema: ConfirmationSchema,
+  }],
+}
+```
+
+Configure `multiRound.state` on the MCP server with a key of at least 32 bytes
+and a stable authenticated `principal`. Read accepted typed content from
+`ctx.mcpInput.confirmation`. Multiple declarations run in array order, the
+aggregate remains exactly typed by key, keys must be unique, and declarations
+must fit `multiRound.serving.maxRounds` (default `10`). Do not execute a
+destructive side effect before the complete aggregate is accepted. A modern
+request missing the declared elicitation capability receives JSON-RPC error
+code `-32021`. The official per-request legacy HTTP bridge cannot issue
+server-to-client elicitation, so it returns a deterministic failed tool result;
+multi-round input is never silently treated as complete.
+
+#### Compatibility matrix
+
+| Host / transport | Tools and Apps | Multi-round input | Continuity |
+|---|---|---|---|
+| `2026-07-28` HTTP | yes | yes | request-isolated |
+| supported legacy stateless HTTP | yes | unsupported result | request-isolated |
+| `2026-07-28` stdio | yes | yes | one process connection |
+| supported legacy stdio | yes | official SDK bridge | one process connection |
+| Agent / CLI / ordinary HTTP | unchanged | not exposed | unchanged |
+
+Subscriptions, cross-request progress and resumable stateful SSE are not
+implemented or advertised.
+
+#### Consumer checklist
+
+1. Replace the monolithic SDK with `@modelcontextprotocol/server@^2` and, only
+   for hosts/tests, `@modelcontextprotocol/client@^2`.
+2. Replace raw MCP route wiring with `createMcpHttpRoute`; retain and close the
+   returned handler/stdio handle during shutdown.
+3. Delete all session mode, event-store and session-id code.
+4. Move OAuth client policy under `clientRegistration`; publish CIMD or enable
+   DCR explicitly.
+5. Snapshot `listToolNames`, run one contract tool, one runtime tool, any raw
+   multimodal tool and every MCP App resource you use.
+6. Exercise modern HTTP and stdio with protocol `2026-07-28`; exercise legacy
+   only if `legacy: 'serve'` is part of your support policy.
+7. Run the consumer's typecheck and runtime gates. A browser/HTTP-only consumer
+   must continue to work without either MCP package.
+
+## Historical breaking migrations through 0.43.1
+
 HTTP observability now completes inside the framework handler instead of a
 nested fetch wrapper. Configure request and tool sinks explicitly:
 
@@ -4709,23 +5046,6 @@ If a tool hook annotated `endpoint` as `MethodDef`, remove that annotation or
 use `OperationIdentity`: native operations have service/action/scope/method but
 no HTTP path.
 
-### MCP HTTP sessions
-
-Finally, replace the MCP HTTP session boolean. Omission changed meaning:
-
-```ts
-// before → after
-stateless: true  // → sessionMode: 'stateless'
-stateless: false // → sessionMode: 'stateful'
-
-// before: omission was stateful
-// after:  omission is stateless
-```
-
-If the client relies on `Mcp-Session-Id`, server push, progress across requests
-or resumable SSE, set `sessionMode: 'stateful'` explicitly. Synchronous tool
-servers should omit it and use the new restart-safe default.
-
 ### Node-facing server types
 
 `stitchkit/server` remains Bun-concrete: an explicitly annotated `RawRoute`
@@ -4839,7 +5159,7 @@ The browser-and-server entrypoint. Re-exports everything from
 | `contractEndpointMatchers` | function | compile exact pathname matchers for selected HTTP contract operations and expected-401 policy |
 | `PathPrefixArgs` | _type_ | required string-valued keys exposed to a typed dynamic `pathPrefix` callback |
 | `createHttpClient` | function | the Ky-based HTTP transport — [guide](../guide/client.md#createhttpclient) |
-| `ApiError` | class | a non-2xx response, with `code` / `status` / `details` / `hint` |
+| `ApiError` | class | a non-2xx response, with `code` / `status` / `details` / `hint` and optional readonly `traceId` from `x-request-id` |
 | `HttpClient` | _type_ | the transport interface `createClient` builds on |
 | `ConfiguredHttpClient` | _type_ | a framework-created `HttpClient` carrying its readonly `baseUrl` for URL builders |
 | `HttpClientConfig` | _type_ | config for `createHttpClient` |
@@ -4874,7 +5194,7 @@ can emit / propagate a `traceparent` (see `HttpClientConfig.trace`).
 | `formatTraceparent` | function | render a `traceparent` header value |
 | `parseTraceparent` | function | parse a `traceparent` header |
 | `childSpan` | function | a child span of a parent trace |
-| `TraceContext` | _type_ | `{ traceId, spanId, parentSpanId? }` |
+| `TraceContext` | _type_ | `{ traceId, spanId, parentSpanId?, tracestate?, baggage? }` |
 
 ---
 
@@ -4921,6 +5241,8 @@ from the root `stitchkit`.
 | `FileDescriptor` | _type_ | a React Native / Expo file — `{ uri, name, type }` |
 | `EndpointToolAnnotations` | _type_ | MCP behavioural hints on an endpoint (`readOnlyHint` / `destructiveHint` / `title`) |
 | `EndpointUiMeta` | _type_ | MCP Apps widget metadata on an endpoint |
+| `EndpointMcpInputRequired` | _type_ | typed MCP multi-round input request (`key`, message and Zod object schema) |
+| `EndpointMcpPolicy` | _type_ | MCP-only endpoint policy containing `inputRequired` |
 
 ### Errors
 
@@ -5138,11 +5460,12 @@ audit event. See the [Observability guide](../guide/observability.md).
 | Export | Kind | Summary |
 |--------|------|---------|
 | `resolveTraceContext` | function | the trace for a request — `traceparent` continued or fresh |
+| `resolvePropagationContext` | function | continue bounded MCP/W3C propagation metadata with optional ambient fallback |
 | `parseTraceparent` | function | parse a `traceparent` header |
 | `formatTraceparent` | function | render a `traceparent` header value |
 | `createTraceContext` | function | a fresh root trace |
 | `childSpan` | function | a child span of a parent trace |
-| `TraceContext` | _type_ | `{ traceId, spanId, parentSpanId? }` |
+| `TraceContext` | _type_ | `{ traceId, spanId, parentSpanId?, tracestate?, baggage? }` |
 
 ### Sanitisation
 
@@ -5160,12 +5483,19 @@ audit event. See the [Observability guide](../guide/observability.md).
 
 ## `stitchkit/tools`
 
-Server-only. Turns contracts into MCP and AI-agent tools. Needs the
-`@modelcontextprotocol/sdk` peer (for MCP) and the `ai` peer (for agents).
+Server-only. Turns contracts into MCP and AI-agent tools. MCP server surfaces
+need the `@modelcontextprotocol/server` v2 peer; MCP hosts/tests use the separate
+`@modelcontextprotocol/client` package. Agent surfaces need the `ai` peer.
+
+Framework-owned MCP tools advertise the exact declared output schema and return
+the validated value unchanged as `structuredContent`, including arrays, scalars
+and `null`. Tools without an output contract advertise and return no structured
+payload.
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createMcpHandler` | function | a complete Streamable-HTTP MCP server — [guide](../guide/mcp-and-agents.md#mcp--createmcphandler) |
+| `createMcpHandler` | function | a stateless dual-era Streamable-HTTP MCP handler — [guide](../guide/mcp-and-agents.md#mcp--createmcphandler) |
+| `createMcpHttpRoute` | function | framework-owned `RawRoute` adapter for an MCP HTTP handler |
 | `createStdioMcpServer` | function | a complete stdio MCP server — [guide](../guide/mcp-and-agents.md#mcp-over-stdio--createstdiomcpserver) |
 | `buildMcpServer` | function | build an `McpServer` from contract/runtime surfaces — the transport-neutral core |
 | `mountMcp` | function | add contract tools to an existing `McpServer` — [guide](../guide/mcp-and-agents.md#mountmcp) |
@@ -5180,9 +5510,12 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 | `resolveMedia` | function | resolve a media reference for a tool result |
 | `validateMcpSchemas` | function | object-shaped assertion over the exact advertised schema surface — compatibility, typed properties and portable formats ([guide](../guide/mcp-and-agents.md#mcp-schema-validation-profile)) |
 | `listToolNames` | function | every contract/runtime tool name with origin, identity and transports — for stable snapshots — [guide](../guide/mcp-and-agents.md#pinning-tool-names--listtoolnames) |
-| `McpHandlerConfig` | _type_ | config for `createMcpHandler` |
-| `McpHttpConfig` | _type_ | HTTP auth, protected-resource and session options composed into `McpHandlerConfig` |
-| `McpSessionMode` | _type_ | `'stateless' \| 'stateful'`; HTTP defaults to request-isolated stateless mode |
+| `McpHandlerConfig` | _type_ | server surface plus stateless HTTP transport config |
+| `McpHttpConfig` | _type_ | HTTP auth, protected-resource, legacy-era and security options |
+| `McpHttpHandler` | _type_ | framework-owned `{ fetch(request), close() }` lifecycle |
+| `McpHttpSecurityConfig` | _type_ | Fetch-boundary Host and Origin allowlists |
+| `McpLegacyPolicy` | _type_ | `'serve' \| 'reject'` protocol-era compatibility policy |
+| `McpStdioHandle` | _type_ | closeable official stdio transport handle |
 | `StdioMcpServerConfig` | _type_ | config for `createStdioMcpServer` |
 | `McpServerBuildConfig` | _type_ | shared config for `buildMcpServer` |
 | `McpServerSharedConfig` | _type_ | transport-neutral options shared by direct and finite surface configs |
@@ -5210,6 +5543,15 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 | `RuntimeToolOutput` | _type_ | output inferred from a runtime tool's optional Zod schema |
 | `RuntimeToolPresenters` | _type_ | optional MCP and AI SDK `toModelOutput` presentation callbacks |
 | `RuntimeMcpPresentation` | _type_ | MCP content/metadata result without framework-owned `structuredContent` or `isError` |
+| `RuntimeMcpInput` | _type_ | typed accepted multi-round input for an opted-in runtime tool |
+| `OAuthClientRegistrationConfig` | _type_ | deterministic pre-registered → CIMD → explicit-DCR client resolution |
+| `CimdClientMetadata` | _type_ | validated Client ID Metadata Document |
+| `CimdClientMetadataFetcher` | _type_ | injectable secure network boundary for metadata loading |
+| `CimdFetchResponse` | _type_ | bounded metadata fetch result passed across the injectable network boundary |
+| `CimdFetchPolicy` | _type_ | CIMD timeout, redirect and size limits |
+| `CimdCachePolicy` | _type_ | bounded HTTP-aware positive/negative cache policy |
+| `CimdCacheEvent` | _type_ | observable CIMD cache hit, miss, revalidation and eviction event |
+| `createSecureClientMetadataFetcher` | function | production HTTPS, DNS/IP-pinned CIMD fetcher |
 | `RuntimeAgentModelOutput` | _type_ | AI SDK model-facing text/JSON/content output returned by `present.agent` |
 | `RuntimeToolTransport` | _type_ | runtime exposure: `'MCP' \| 'AGENT'` |
 | `AgentMountConfig` | _type_ | config for `mountAgent` |