@gjermundgaraba/effect-actions 0.10.0 → 0.12.0

package/docs/ActionMcp.md

@@ -1,223 +1,259 @@
 # ActionMcp
 
-MCP tools from implementations, on Effect's native `McpServer`. One `Tool` per served action,
-named after it. Two transports: a Streamable HTTP endpoint mounted on the router, or newline-delimited
-JSON-RPC on standard I/O for a subprocess. HTTP speaks MCP 2026-07-28 only; stdio also speaks
-2025-11-25 and 2025-06-18, as the host negotiates.
+MCP tools from implementations, on Effect's native `McpServer`: one tool per served action, named
+after it. `layerHttp` mounts a Streamable HTTP endpoint, for clients that connect to a URL;
+`runStdio` is the whole program of a subprocess a local agent starts. For a model your own code
+calls in process, use [ActionToolkit.md](ActionToolkit.md).
+
+Read this page alone, in one tool call: pages read together are cut. When something fails,
+search [ActionMcp-failures.md](ActionMcp-failures.md). Reading order: [README.md](README.md).
 
 ## API
 
 Import `@gjermundgaraba/effect-actions/ActionMcp`.
 
-| API                                   | Purpose                                                                                            |
-| ------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `layerHttp(implementations, options)` | Serve implementations at a Streamable HTTP endpoint.                                               |
-| `runStdio(implementations, options)`  | Serve implementations as a subprocess's program on standard I/O; succeeds when the host closes it. |
-
-The options, exported as `LayerHttpOptions` and `Options` (the server's, which `LayerHttpOptions` extends), are the native
-`McpServer.layerHttp` / `McpServer.layerStdio` options, except `protocols`, plus `actions` and `features`, and for `layerHttp`, `authentication`. The native ones pass through unchanged; `path` gains a default. Each implementation brings its
-authorization ([Action.md](Action.md#implementations)); an endpoint serving protected actions
-names their authentication descriptor and requires its provider
-([Authentication.md](Authentication.md)).
-
-| Option                               | Meaning                                                                        |
-| ------------------------------------ | ------------------------------------------------------------------------------ |
-| `name`, `version`                    | Required native server information.                                            |
-| `description`, `websiteUrl`, `icons` | Optional native server information, sent to clients with `name` and `version`. |
-| `instructions`                       | Optional native server instructions.                                           |
-| `extensions`                         | Optional native server capability extensions.                                  |
-| `path`                               | HTTP endpoint path; HTTP only, defaults to `/mcp`.                             |
-| `allowedOrigins`                     | Optional exact Origin allowlist; HTTP only, not CORS configuration.            |
-| `authentication`                     | HTTP only: the protected tools' descriptor, required where one is served.      |
-| `actions`                            | Optional actions that are tools, among the implementations'; defaults to all.  |
-| `features`                           | Optional native resources, prompts and tools served beside the actions' tools. |
-
-`implementations` is one implementation or a list. Every tool declares its action's errors plus the
-built-in `InvalidInput`, `Unauthenticated` and `Forbidden`. `layerHttp`'s layer and `runStdio`'s
-program retain the build failures and requirements of their builders, plus native
-`IllegalArgumentError`. HTTP needs the router, the descriptor's provider where it serves a
-protected action, and wraps handler and authorizer services as request requirements until middleware provided around it provides them, the
-identity excepted, which the provider supplies. stdio needs `Stdio` and the caller's request
-services, the identity of its protected tools included. Native `McpRequestContext`
-is supplied by the server, not required of the host. The server also fails as its `features` do
-and needs what they need, except the registry, `McpServer.McpServer`, which the endpoint provides,
-such as to a feature registering with `McpServer.registerResource`.
-
-## Canonical
-
-One endpoint serves the public and the protected tools: discovery and `status` answer anyone,
-and every other request authenticates before the endpoint decodes it.
-
-```ts example=mcp.ts
-import { Layer } from "effect";
-import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
-import { authenticate } from "./authentication.js";
-import { Login } from "./binding.js";
-import { double, status, userActions } from "./handlers.js";
-
-const allowedOrigins = ["http://localhost:3000", "http://127.0.0.1:3000"];
-
-// One URL: discovery and `status` answer anyone; a protected tool's call authenticates
-// before its arguments are decoded, with the 401 an MCP client signs in on.
-export const layer = ActionMcp.layerHttp([status, userActions, double], {
-  name: "effect-actions",
-  version: "0.0.0",
-  allowedOrigins,
-  authentication: Login,
-}).pipe(Layer.provide(authenticate));
-```
-
-### Cross-origin browsers
+| API                                   | Purpose                                                      |
+| ------------------------------------- | ------------------------------------------------------------ |
+| `layerHttp(implementations, options)` | A Layer serving the actions as tools at one HTTP endpoint.   |
+| `runStdio(implementations, options)`  | An Effect serving them on standard I/O until stdin closes.   |
+| `Options`                             | Type of `runStdio`'s options.                                |
+| `LayerHttpOptions`                    | Type of `layerHttp`'s options: `Options` and three for HTTP. |
 
-`allowedOrigins` alone does not configure CORS. For a stateless browser endpoint, mount
-native router CORS outside the route middleware. This CORS layer is global to the router;
-choose its policy for every route it covers.
+`implementations` is one implementation or a list.
 
-```ts example=mcp-browser.ts
-import { Effect, Layer } from "effect";
-import { HttpRouter } from "effect/http";
-import * as Action from "@gjermundgaraba/effect-actions/Action";
-import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
-import { Greet } from "./quickstart.js";
+| Option                               | Meaning                                                    |
+| ------------------------------------ | ---------------------------------------------------------- |
+| `name`, `version`                    | Required server information.                               |
+| `description`, `websiteUrl`, `icons` | Optional server information.                               |
+| `instructions`                       | Optional text for the model about the server as a whole.   |
+| `extensions`                         | Optional native capability extensions.                     |
+| `actions`                            | The implementations' actions that are tools; default all.  |
+| `features`                           | One Layer of native resources, prompts and tools to serve. |
+| `path`                               | HTTP only: the endpoint's path; defaults to `/mcp`.        |
+| `allowedOrigins`                     | HTTP only: the exact origins allowed; none by default.     |
+| `authentication`                     | HTTP only: the protected tools' authentication descriptor. |
 
-const allowedOrigins = ["https://ui.example.com"];
+All but `actions`, `features` and `authentication` are Effect's own `McpServer` options, passed
+through. Its `protocols` and `allowSessionTermination` are not options.
 
-const actions = Action.implement(Greet, ({ name }) => Effect.succeed(`Hello, ${name}!`));
+## Serve tools over HTTP
 
-const mcp = ActionMcp.layerHttp(actions, { name: "greetings", version: "1.0.0", allowedOrigins });
+Merge `layerHttp` into the routes, beside any other surface, and serve them with
+`HttpRouter.serve`:
 
-// Global router CORS handles preflight outside route-level authentication.
-// This example is public; an endpoint serving protected actions takes their `authentication`.
+```ts
 export const routes = Layer.mergeAll(
-  mcp,
-  HttpRouter.cors({
-    allowedOrigins,
-    allowedMethods: ["POST"],
-    allowedHeaders: [
-      "Content-Type",
-      "Authorization",
-      "MCP-Protocol-Version",
-      "MCP-Method",
-      "MCP-Name",
-    ],
-    exposedHeaders: ["WWW-Authenticate", "MCP-Protocol-Version"],
-  }),
+  ActionHttp.layer(Http, greeting),
+  ActionMcp.layerHttp(greeting, { name: "greetings", version: "1.0.0" }),
 );
 ```
 
-### Subprocess
-
-```ts example=mcp-stdio.ts
-import { NodeRuntime, NodeStdio } from "@effect/platform-node";
-import { Effect, Schema } from "effect";
-import * as Action from "@gjermundgaraba/effect-actions/Action";
-import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
-import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+See [quickstart/src/routes.ts](../examples/quickstart/src/routes.ts) and
+[quickstart/src/server.ts](../examples/quickstart/src/server.ts). Surfaces given the same
+implementations in one set of routes run each builder once, so a note written over HTTP is read
+as a tool: [notes-service/src/routes.ts](../examples/notes-service/src/routes.ts). For two
+servers, see [Action-in-process.md](Action-in-process.md#share-one-build-across-servers).
+
+- The endpoint speaks MCP 2026-07-28, 2025-11-25 and 2025-06-18, as the client negotiates.
+  Claude Code 2.1 and Codex CLI 0.162 both connect, as tested in October 2026:
+  [notes-service](../examples/notes-service/README.md#run-it) has the commands,
+  [mcp-tools](../examples/mcp-tools/README.md#connect-a-client) those for stdio and Claude Desktop.
+- **A client of a 2025 revision opens a session** with `initialize`; a 2026-07-28 request stands
+  alone. A session holds what its client sent there and no identity: each request authenticates,
+  as its own caller. It lasts until its client ends it with a `DELETE`, answered 204, or the process stops, as
+  Effect expires none, so limit request bodies, which bounds what one holds. Where an endpoint
+  serves a protected tool, only a signed-in caller opens one, and that client signs in for every
+  request, a public tool's call included. An endpoint of public tools alone lets anyone open them.
+- An endpoint without `authentication` answers whoever reaches its port. Bind it to loopback or to
+  a network only trusted clients are on, and limit request bodies
+  ([ActionHttp.md](ActionHttp.md#serve-the-routes)):
+  [mcp-tools/src/server.ts](../examples/mcp-tools/src/server.ts).
+- The endpoint takes no layer middleware. A limit that must hold for tools goes in the handlers:
+  [kitchen-sink/src/issues/write-limit.ts](../examples/kitchen-sink/src/issues/write-limit.ts).
+
+## Serve tools over stdio
+
+Provide `Stdio` and the startup services, then run it:
 
-const Status = Action.make("status", {
-  description: "Report whether the subprocess is ready.",
-  success: { ready: Schema.Boolean },
-  readOnly: true,
-  caller: Action.Anyone,
-});
-
-const status = Action.implement(Status, () =>
-  Effect.log("status called").pipe(Effect.as({ ready: true })),
-);
-
-// Serves until the host closes stdin, then exits 0. Protocol messages use stdout
-// exclusively: runStdio writes its program's Effect logs and `Console` output to stderr, and
-// `logToStderr`, applied last, does so for the layers provided around it, and reports a failure
-// there rather than as runMain would, on stdout.
-ActionMcp.runStdio(status, { name: "effect-actions-stdio", version: "0.1.0" }).pipe(
-  Effect.provide(NodeStdio.layer),
+```ts
+ActionMcp.runStdio([status, notes, identity], { name: "notes-service", version: "1.0.0" }).pipe(
+  // DEMO ONLY: a real host reads who started it, from its own login or configuration.
+  Effect.provideService(CurrentUser, users.ada),
+  Effect.provide([NodeStdio.layer, NoteStore.layerMemory]),
   ActionCli.logToStderr,
   NodeRuntime.runMain,
 );
 ```
 
-### Native features
+See [notes-service/src/stdio.ts](../examples/notes-service/src/stdio.ts), and
+[mcp-tools/src/stdio.ts](../examples/mcp-tools/src/stdio.ts) for public tools.
 
-Effect's own resources, prompts and tools join an endpoint's tools as its `features`, one layer
-merging them:
+To try a server by hand, send it one request, its 2026-07-28 metadata in `_meta` as
+`Testing.mcpRequest` builds it. Over HTTP it also needs all five headers:
+
+```sh
+BODY='{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"getStatus","arguments":{},"_meta":{"io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}'
+echo "$BODY" | node --import tsx examples/notes-service/src/stdio.ts
+curl http://127.0.0.1:3000/mcp -d "$BODY" -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' -H 'MCP-Protocol-Version: 2026-07-28' \
+  -H 'MCP-Method: tools/call' -H 'MCP-Name: getStatus'
+```
+
+- **stdout carries the protocol alone.** `runStdio` sends its own program's Effect logs and
+  `Console` output to stderr. For the layers provided around it, apply `ActionCli.logToStderr`
+  last, before `runMain`: it moves their default logger and reports a startup failure there too.
+  Nothing moves the global `console.log`: keep it off stdout.
+- **A subprocess has its own services.** It runs the handlers itself, so it shares a server's
+  data only through a store both reach, never one in memory. A host that should see what the
+  server holds connects to its HTTP endpoint.
+- **No token arrives, so the host names the caller.** stdio takes no `authentication`: provide the
+  protected tools' identity around `runStdio`, whose one caller is whoever started it. Each
+  implementation's `authorize` still runs, so give that caller what it checks. Tools served
+  behind a token over HTTP keep their one protected contract here: never a public copy. An HTTP
+  server has many callers: never provide an identity at its startup, where it would stand for
+  every request.
+- **Test the tools without a process**: the implementations in process over a fake upstream
+  ([mcp-tools/test/printers/printers.test.ts](../examples/mcp-tools/test/printers/printers.test.ts)),
+  an endpoint in memory
+  ([mcp-tools/test/routes.test.ts](../examples/mcp-tools/test/routes.test.ts)).
+
+## Describe tools to a model
+
+A tool is its contract ([Action.md](Action.md#define-a-contract)): a model knows only the action's
+name, its `description`, and its input schema with each field's `description`. `readOnly` is the
+tool's read-only hint, and the contract's `mcp` option holds its `title`, its other hints and its
+`_meta`. The server's `instructions` say what the tools are for together. See
+[mcp-tools/src/printers/Printers.ts](../examples/mcp-tools/src/printers/Printers.ts) and
+[mcp-tools/src/instructions.ts](../examples/mcp-tools/src/instructions.ts).
+
+- MCP takes a write as destructive unless it states `destructiveHint: false`.
+- A tool's input is one object with keys. Omit `input` for a tool without arguments, and wrap a
+  union, an array or a scalar in a field.
+- An argument the schema refuses, an undeclared one included, is answered by the native server
+  before the handler runs, as an `isError` result whose text is `Invalid parameters for tool
+  '<name>': …`, not `InvalidInput`. So constrain in the schema
+  what a model may send: an id written into an upstream URL is not made safe by
+  `encodeURIComponent`, which leaves `..` alone.
+- A `Schema.makeFilter` check adds nothing to the tool's listed input schema, and
+  `Schema.isPattern` its `pattern` only for a RegExp with the `u` flag. Say such a rule in the
+  field's `description`, annotated before the check: after a custom one it is lost too.
+- A declared error reaches the model as an `isError` result whose text is the error's JSON. Write
+  its `message` for the model, which acts on it:
+  [mcp-tools/src/printers/farm.ts](../examples/mcp-tools/src/printers/farm.ts). Every other case:
+  [guarantees.md](guarantees.md#wire-behavior).
+- `actions` lists the tools, and only listed actions must suit MCP:
+  [kitchen-sink/src/Actions.ts](../examples/kitchen-sink/src/Actions.ts). Leave out an action a
+  model should not call, or one that takes a secret ([Action.md](Action.md#define-a-contract)).
+
+## Return images and other media
+
+Give the success an `Action.Image` field, the one media kind, and return its bytes and MIME type
+from the handler:
 
 ```ts
-ActionMcp.layerHttp(app, {
-  name: "acme",
+success: { printer: Printer, image: Action.Image },
+```
+
+The tool sends the field as an image block, after the JSON of the rest. Every other surface sends
+it as JSON, the bytes in base64. See
+[mcp-tools/src/printers/Printers.ts](../examples/mcp-tools/src/printers/Printers.ts), and
+[Testing.md](Testing.md#test-mcp-tools) for the client that decodes it back.
+
+- An image is a top-level field of a struct success, bare, optional or a required array, or the
+  whole success or an array of it. Anywhere else in a served action, as in a `Schema.NullOr`, a
+  `Schema.Class` success or an input, `layerHttp` and `runStdio` throw. So an action taking an
+  image as input is no tool: leave it out of `actions`
+  ([kitchen-sink/src/attachments/Attachments.ts](../examples/kitchen-sink/src/attachments/Attachments.ts)).
+- A media field's own `description` reaches no model. Describe the image in the action's
+  `description`.
+
+## Protect tools
+
+Name the protected actions' authentication descriptor and provide its provider to the routes:
+
+```ts
+const mcp = ActionMcp.layerHttp(implementations, {
+  name: "notes-service",
   version: "1.0.0",
-  features: Layer.mergeAll(
-    McpServer.resource({ uri: "docs://readme", name: "README", content: Effect.succeed("# Acme") }),
-    McpServer.prompt({ name: "triage", content: () => Effect.succeed("Triage the issue.") }),
-  ),
+  authentication: Login,
 });
+
+export const routes = Layer.mergeAll(api, mcp, health, openApi).pipe(Layer.provide(authenticate));
 ```
 
-They are native: no implementation's authorization runs for them. On an endpoint
-naming a descriptor, every request a feature answers authenticates, its listings, completions
-and subscriptions included, so a public resource or prompt beside protected tools takes an
-endpoint of its own. The features register before the actions, and a native tool named as an
-action is refused when the endpoint builds: Effect's registry keeps one tool per name, and the
-endpoint's authentication decides by that name. A service they need, provided around the endpoint, is shared with the rest of the graph; one
-provided to the `features` layer itself is built once per endpoint.
-
-A feature runs with the services it was built with, never a request's: Effect's `resource` and
-`prompt` run their content in their build context alone, so a feature cannot read the caller.
-Content that depends on the caller is an action. Never provide an identity at startup to
-satisfy a feature.
-
-## Rules
-
-- HTTP serves MCP 2026-07-28 and no other revision: it is stateless, every request standing alone. The stateful revisions keep a session per `initialize`, which Effect's HTTP runtime never expires and which no identity owns. Stdio serves 2026-07-28, 2025-11-25 and 2025-06-18, whichever the host negotiates. There is no `protocols` option; Effect owns version checks and negotiation.
-- `path` defaults to `/mcp`. `layerHttp` uses the single-endpoint Streamable HTTP transport, never the two-endpoint HTTP+SSE form.
-- Requests reaching the native MCP handler with an `Origin` header receive **403** unless that exact origin is listed in `allowedOrigins`. Requests without `Origin` pass this check. The endpoint's authentication runs first and may reject the request before native Origin validation; the allowlist does not protect authentication from untrusted-origin requests: a check that must run before it is global middleware ([Authentication.md](Authentication.md#rules)).
-- `allowedOrigins` is an Origin allowlist, not CORS configuration. Cross-origin browser clients also need outer CORS middleware or a proxy to handle preflight and add response headers. Without it, an allowed-origin `OPTIONS` request receives **405** and even a successful `POST` has no `Access-Control-Allow-Origin`. Keep preflight outside authentication and apply CORS headers to refusals too.
-- An endpoint serving a protected action names its descriptor, `authentication: Login`, and requires its provider, `Layer.provide(authenticate)`; the types refuse one without it, and `layerHttp` throws for plain JavaScript. One serving only public actions names none, and authenticates nothing.
-- An endpoint whose every tool is protected authenticates every request before reading its body, so a host signs in when it connects.
-- A mixed endpoint, serving public and protected tools on one URL, decides from the request's MCP routing headers before the native server reads its body, as the native server refuses a request whose headers disagree with its body. Discovery, `server/discover` and `tools/list`, `notifications/cancelled`, and a call of a public tool pass without a credential; a credential presented there is verified, and refused with 401 if it does not verify, while one its scheme decodes as empty passes as none. Every other request authenticates: a protected tool's call, before its arguments are decoded, and every native feature's request, `prompts/get`, `resources/read`, their listings, `completion/complete` and `subscriptions/listen` included, as does a method a later revision adds. The `Mcp-Name` header is compared as it is: a `tools/call` naming no public tool by it, a Base64-encoded name (`=?base64?...?=`) included, authenticates, and so does a request whose headers name no method: it fails closed.
-- So signed-out callers of a mixed endpoint list every tool, protected ones included, and call the public ones; a protected tool's call answers the 401 an MCP client signs in on, then retries. To keep protected tools unlisted to signed-out callers, serve the public tools on an endpoint of their own, with separate `layerHttp` calls on different paths.
-- A public tool never gets the identity, signed in or not; an action whose answer depends on the caller is protected. Middleware provided around `layerHttp` covers every request to the endpoint, before its authentication; an endpoint takes no layer middleware of its own, so middleware that reads the identity is not available over MCP ([ActionHttp.md](ActionHttp.md#rules)).
-- Every action of the implementations passed becomes a tool, named after the action, with the action's `mcp` hints, its `title` and `_meta` included, unless `actions` lists the tools: then only those, each behind its implementation's authorizer and from its builder's one run, and an implementation holding none of them is not built. To keep an action off MCP, leave it out of `actions`: `ActionMcp.layerHttp([users, pages], { name, version, actions: Tools })` ([Action.md](Action.md#contracts)). Only a listed action's input must suit MCP, and only listed actions' names must be unique. The types take only actions of the implementations, and owe only what the listed actions' handlers and authorizers, and the builders holding them, need. Whether the endpoint authenticates follows the listed actions alone.
-- Builders and request services follow the [dependency lifetimes](guarantees.md#dependency-lifetimes), and authorization the [authorization rules](guarantees.md#authorization). Only the tool registry is fresh per endpoint.
-- A handler may yield `McpServer.McpServer`, its endpoint's registry, to send notifications such as progress: the endpoint provides it, and no host owes it. Served on another surface too, where nothing provides it, read it with `Effect.serviceOption`.
-- Every served action's input must be one object with keys, as a tool's arguments are: fields, a struct or a class, identified, recursive or suspended, a record, or a declared type whose JSON Schema is an object. `layerHttp` and `runStdio` read the JSON Schema the native server reads, and throw for any other when they are called, naming the actions: a union, an array, a scalar, or an object without keys such as `Schema.Struct({})`. Omit `input`, or give `{}`, for a tool with no arguments.
-- A tool's `inputSchema` is its input's JSON Schema, on every revision, closed with `additionalProperties: false` where the input declares its fields; a record's lists its value schema there instead. Undeclared arguments are refused on every revision, as invalid arguments.
-- A success is sent as it is. On 2026-07-28, over HTTP and stdio, it is `structuredContent: <encoded success>`, of any JSON type (`null` for an action that returns nothing), and one text block holding the same JSON, and the tool's `outputSchema` describes the encoded success. Stdio's earlier revisions, 2025-11-25 and 2025-06-18, structure less: they carry only an object as `structuredContent`, and list only an object-rooted `outputSchema`. A success they do not structure is text alone: its JSON, or a string success the string itself. A declared error is an `isError` result whose text content is the error's JSON encoding, the same bytes HTTP sends as the body, and no `structuredContent`.
-- On 2026-07-28, over HTTP and over stdio, the native server adds `_meta["io.modelcontextprotocol/serverInfo"]` and `resultType: "complete"` to every result, beside a tool result's own fields (`isError: false` on a success); the earlier revisions stdio speaks add neither. `serverInfo` is the options' `name`, `version`, `description`, `websiteUrl` and `icons`, as given, so a 2026-07-28 result's encoded size is the size of its own fields plus a fixed overhead per endpoint or subprocess.
-- Invalid arguments are answered by the native `McpServer`: from 2025-11-25 on, an `isError` result with a message for the model, such as `Invalid parameters for tool 'greet': Expected string\n  at ["name"]`; on earlier stdio revisions, a JSON-RPC error. HTTP's `InvalidInput` does not apply. A protected tool's call from a caller without a credential that verifies gets the 401 first, before its arguments are decoded, malformed ones included, on a mixed endpoint as on one of protected tools alone.
-- Defects and encoding failures produce the generic `isError` text `Tool execution failed due to an internal server error.`; the cause is logged, not sent.
-- Every caller sees every tool of the endpoint ([guarantees.md](guarantees.md#scope)); authorization happens in each implementation's `authorize`.
-- Cancellation is Effect's native RPC interruption. Over HTTP there is no session, so `notifications/cancelled` interrupts nothing. A tool call ends with its HTTP request, whose lifetime (for example, whether a client disconnect interrupts it) is the host's.
-- Handlers may yield `McpSchema.McpRequestContext` for the client's declared information; the native server supplies it to every tool call, so it is never a router or host requirement.
-- `runStdio` is the subprocess's whole program: it serves until the host closes stdin, then succeeds, so the process exits 0. Closing stdin interrupts every call in flight; `runStdio` succeeds once they have stopped, after any uninterruptible region has completed. An interrupted call gets no result: no answer, or a JSON-RPC error. MCP hosts close stdin to shut a server down; a script piping requests keeps stdin open until it has read every answer. A signal interrupts it, as any program. Provide `Stdio` and its services to it and run it, `NodeRuntime.runMain`.
-- stdio is a local surface and takes no `authentication`: the host supplies `Stdio` (`NodeStdio.layer`) and any request-time services explicitly around `runStdio`, the identity of every protected tool included, `Effect.provideService(CurrentActor, actor)`. Each implementation's `authorize` runs for its protected tools. Tool arguments never establish identity.
-- `runStdio` gives its program a `Console` that writes every method through the `error` of the console it runs with, to stderr, since stdout carries the protocol: every console logger, the default one included, `Console.log`, and the counters, timers and group labels Node's console prints on stdout. A counter or a timer prints its label and its count or the milliseconds since it started, a group prints its label without indenting what follows, and `clear` does nothing. Layers provided around `runStdio` run outside its program: apply `ActionCli.logToStderr` last, before `runMain`, as the example does, which moves their default logger to stderr and reports there what `runMain` would report on stdout, a failure of such a layer or a defect, with the exit code `runMain` gives ([ActionCli.md](ActionCli.md#rules)). It does not move their `Console` output or a logger writing through `Console.log`, such as `Logger.consoleJson`; log JSON with `Logger.withConsoleError(Logger.formatJson)` instead. Keep the global `console.log` and other direct writes off stdout.
-- Each endpoint or subprocess owns a fresh native tool registry. That isolates tool names, not application context.
-- Every tool declares the built-in errors ([guarantees.md](guarantees.md#wire-behavior)). An authorizer's refusal is an `isError` result whose text is its JSON, `{"_tag":"Forbidden","message":"Not allowed."}`, exactly like an action's own error.
-- The authorizer runs after the native server decodes the tool's arguments.
-- On an endpoint naming a Bearer descriptor, a protected tool's step-up refusal is an HTTP 401 or 403 instead of a tool result ([guarantees.md](guarantees.md#authorization)); a public tool's is its `isError` result, signed in or not; without one, or under a descriptor of another scheme, a tool's refusal is an `isError` tool result, and only the authentication's own refusal is a 401 or 403. On a `Forbidden`'s `insufficient_scope` challenge, an MCP client re-authorizes with those scopes and retries.
-- That holds only while nothing of the response has been sent. Once a handler's notification, such as progress, has started a 200 event stream, a later refusal is the tool's `isError` result in it. An authorizer runs before its handler, so its refusal is always the status.
-- Authentication refuses before the MCP handler too: an HTTP 401 or 403. An MCP client reads the 401's `WWW-Authenticate` challenge and finds its authorization server through the discovery `Authentication.layer` publishes for a protected resource ([Authentication.md](Authentication.md)).
-
-## Failure modes
-
-- `MCP tool input must be one object with keys, such as a struct: <name>, ...` thrown by `layerHttp` or `runStdio`: those actions' input is a union, an array, a scalar, or an object without keys such as `Schema.Struct({})`. Wrap a union in a field, `input: { notification: Schema.Union([Email, Sms]) }`, omit `input` (or give `{}`) for no arguments, or leave the action out of `actions`.
-- `Type 'CurrentActor' is not assignable to type 'never'` where the server is launched, with `CurrentActor` among the endpoint's startup requirements rather than its `Request<"Requires", ...>`: a feature reads a request service, which it never receives ([native features](#native-features)). Serve that content as an action.
-- A native `McpServer.resource`, `McpServer.prompt` or `McpServer.toolkit` layer merged beside `layerHttp` builds without error and is never served: `resources/list` is empty, `prompts/list` is not found, and `tools/list` lists only the actions. Each endpoint's registry is its own: pass them as its `features`.
-- An MCP client gets an `isError` refusal instead of the 401 or 403 it re-authorizes on: the handler sent a notification before refusing, so the response had already started. Refuse in the implementation's `authorize`, before the handler runs.
-- `Duplicate MCP tool: <name>` thrown at the `layerHttp` or `runStdio` call: two implementations on one endpoint serve actions of the same name. Split the endpoint, or rename one action. `actions` tells apart only separate contracts sharing a name, listing one; two implementations of the same contract stay both listed: pass one implementation.
-- `Duplicate MCP tool: <name>, claimed by an action and a native feature`, a defect when the endpoint builds: a native tool among its `features` has an action's name. Rename the native tool, or leave the action out of `actions`.
-- `Listed in actions, but no implementation holds it: <names>` thrown at the `layerHttp` or `runStdio` call: those actions are not among the implementations' actions, by identity. `(another contract)` marks one whose name an implementation holds, as a second copy of the contracts module makes. Pass the implementation holding it, or list the contract it implements.
-- `No overload matches this call` at `layerHttp`, ending `Type 'string' is not assignable to type 'never'` on its options: the endpoint serves a protected action and names no `authentication`, or one of another identity. Give its descriptor. `Protected action '<name>' requires its matching authentication descriptor` thrown by `layerHttp`: the same, from plain JavaScript.
-- `Provider<CurrentActor, "example.Login">` among the endpoint's requirements, or `Type 'Provider<...>' is not assignable to type 'never'` where the server is launched: the descriptor's provider is not provided. `Layer.provide(authenticate)` on that `layerHttp` ([Authentication.md](Authentication.md#failure-modes)).
-- `Type 'X' is not assignable to type 'never'` where the server is launched, or `Request<"Requires", X>` in the endpoint's type: a handler or an authorizer yields a request service that no middleware around the endpoint provides. Provide it with router middleware on that `layerHttp`; never an identity at startup. `X` the identity, on an endpoint serving public tools: a public handler reads it, which no public tool gets. Make that action protected.
-- A public tool's call answers 401: it presented a credential that does not verify. Send a valid one, or none.
-- A protected tool's call answers 401 to a signed-in host after a while: its token expired; the host refreshes it, or signs in again, on the challenge's `invalid_token`.
-- A prompt or resource demands credentials: it is served on an endpoint naming a descriptor, where every feature request authenticates. Serve it on an endpoint without protected tools.
-- A stdio program owes `CurrentActor`, `Type 'CurrentActor' is not assignable to type 'never'` at `runMain`: it serves a protected tool, whose caller the host supplies. Provide it around `runStdio`; stdio takes no `authentication`.
-- Client reports a broken transport from a stdio subprocess: something wrote to stdout, such as `console.log`, or a layer provided around `runStdio` did, through the default logger without `Logger.LogToStderr` outermost, or through `Console` or a logger such as `Logger.consoleJson`, which `LogToStderr` does not move. Remove the write, apply `ActionCli.logToStderr` last, or log JSON with `Logger.withConsoleError(Logger.formatJson)`.
-- A stdio host asking for 2025-03-26 or 2024-11-05 is offered 2025-11-25 in the `initialize` result, as MCP negotiates, and disconnects if it cannot speak it. Update the host.
-- An MCP client cannot connect over HTTP: a request answers `400` with JSON-RPC error `-32020`. The client opens with `initialize`, as the 2025 revisions do, and HTTP serves only 2026-07-28. Pin the client to it (the official client: `versionNegotiation: { mode: { pin: "2026-07-28" } }`), or serve that host over stdio. Codex is such a client: it opens HTTP with `initialize` (measured on 0.159.0), so serve it over stdio.
-- An Origin-bearing request reaches the native handler and gets an empty 403: its `Origin` is not in `allowedOrigins`. Add the exact origin only if the deployment trusts it.
-- A disallowed Origin receives 401 instead: the endpoint's authentication rejected it before the native Origin check. A Host or Origin check that must run before authentication is global middleware ([Authentication.md](Authentication.md#rules)).
-- Browser calls fail despite an allowed Origin: configure CORS outside authentication and the MCP handler (see the browser example above). The native allowlist alone neither handles preflight nor adds CORS response headers.
-- `Object literal may only specify known properties, and 'protocols'`: the revisions are fixed. Delete the option.
+See [notes-service/src/routes.ts](../examples/notes-service/src/routes.ts). Write the
+[descriptor](Authentication.md#declare-how-callers-sign-in) and its
+[provider](Authentication.md#verify-credentials) once for every surface, and
+[publish discovery](Authentication.md#publish-oauth-discovery) so an MCP client finds where to
+sign in. What a signed-in caller may do is each implementation's
+[`authorize`](Action.md#authorize-calls), which runs on every call of a protected tool.
+
+- **One endpoint or two.** An endpoint of protected tools alone authenticates every request,
+  the listing included. On a mixed endpoint, serving public and protected tools, a 2026-07-28
+  request lists every tool, protected ones included, and calls a public one signed out, and a
+  session's every request signs in ([Serve tools over HTTP](#serve-tools-over-http)). A
+  protected tool's call answers the 401 a client signs in on. To keep protected tools unlisted
+  to signed-out callers, or public ones open to a session's client, serve the public tools on an
+  endpoint of their own: a second `layerHttp` on another `path`.
+- No listing is filtered by caller: `authorize` refuses the call, not the sight of the tool.
+- On a Bearer endpoint, a protected tool's `Unauthenticated`, or `Forbidden` naming `scopes`,
+  answers the request with 401 or 403 and a challenge the client acts on, in place of a tool
+  result ([Authentication.md](Authentication.md#step-up-for-a-scope)). A `Forbidden` naming none
+  is an `isError` tool result, in a 200. Once a handler has sent a notification the response has
+  started, and its refusal is a tool result: refuse in `authorize`.
+- Test as a signed-in caller ([Testing.md](Testing.md#test-as-a-signed-in-caller)):
+  [notes-service/test/routes.test.ts](../examples/notes-service/test/routes.test.ts).
+  `Testing.mcpClient` decodes a refusal alike from a 401, a 403 or a tool result: to assert the
+  status, send `Testing.mcpRequest`.
+
+## Allow browser clients
+
+A browser MCP client sends its page's `Origin`, and needs two things.
+
+- **`allowedOrigins`.** A request carrying an `Origin` is refused with 403 unless that exact
+  origin is listed, so a page a user happens to visit cannot call the tools; one without, as
+  other clients send, passes. Read the list from configuration:
+  [mcp-tools/src/routes.ts](../examples/mcp-tools/src/routes.ts).
+- **CORS.** `allowedOrigins` only refuses: it answers no preflight and adds no header. Add
+  `HttpRouter.cors`, global to the router, only where an origin is configured: given an empty
+  list, it answers `Access-Control-Allow-Origin: *`, and given one origin it names that origin
+  to every request, an unlisted page's included, which `allowedOrigins` still refuses. Allow the methods `POST` and
+  `DELETE`, the endpoint's only ones, and the headers `Content-Type`, `Authorization`,
+  `MCP-Protocol-Version`, `MCP-Method`, `MCP-Name` and `Mcp-Session-Id`; expose
+  `WWW-Authenticate`, `MCP-Protocol-Version` and `Mcp-Session-Id`: the same `routes.ts`, and
+  [kitchen-sink/src/request-policy.ts](../examples/kitchen-sink/src/request-policy.ts) with
+  authentication.
+
+The endpoint's authentication runs before its Origin check, so `allowedOrigins` keeps no request
+from the verifier. A `Host` allowlist, for a request that sends no `Origin`, or an Origin check
+that must run first is a request policy:
+[Authentication-advanced.md](Authentication-advanced.md#run-a-request-policy-before-authentication).
+
+## Add native prompts and resources
+
+Merge Effect's own `McpServer.resource`, `McpServer.prompt` and `McpServer.toolkit` layers into
+one and pass it as `features`:
+[kitchen-sink/src/issues/guide.ts](../examples/kitchen-sink/src/issues/guide.ts), given in
+[kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts) and
+[kitchen-sink/src/stdio.ts](../examples/kitchen-sink/src/stdio.ts). Provide a service they need
+around the endpoint, never to the `features` layer itself: there it is built again for the
+features alone, so a resource reads another store than the tools write.
+
+- Merged beside the endpoint, not given as `features`, they build and are never served.
+- No `authorize` runs for them, and they run with the services they were built with, never a
+  request's, so they cannot read the caller. Content that depends on the caller is an action.
+- On an endpoint naming `authentication`, every prompt and resource request needs a credential,
+  listings included. To offer them to signed-out callers, serve them on an endpoint without
+  protected tools.
+
+## Send notifications from a handler
+
+A handler yields `McpServer.McpServer` and sends through it:
+`server.notifications["notifications/progress"]({ progressToken, progress })`.
+`McpSchema.McpRequestContext` holds what the client sent: its `clientInfo`, and the request's
+`_meta` as `requestMetadata`. The endpoint and `runStdio` provide both; an implementation also
+served on another surface reads them with `Effect.serviceOption`.
+
+- On 2026-07-28, a progress notification is sent only with the token its request carried,
+  `requestMetadata?.progressToken`. With another, or when the client sent none, it is dropped
+  silently.

package/docs/ActionRpc-failures.md

@@ -0,0 +1,21 @@
+# ActionRpc failure modes
+
+What you see when something is wrong, and the fix. Search for a fragment of the message.
+The tasks are in [ActionRpc.md](ActionRpc.md).
+
+- `No action of these implementations is in this RPC binding: <names>` thrown by `layer`: none of the implementations' actions was passed to this binding's `make`. Implement the contract value the binding received; `(another contract)` marks an equal-looking copy.
+- `Listed in actions, but the binding does not hold it: <names>`, or `but no implementation holds it`, thrown by `layer`: an action in `layer`'s `actions` is not the binding's or the implementations', by identity.
+- `Duplicate served action: <name>` thrown by `layer`: one `layer` call received two implementations of one bound action. Pass one.
+- `ActionRpc binding: error _tag "<tag>" is built in, and declared on every surface` thrown by `make`: the binding's `error` holds a built-in error, or one reusing a built-in tag. Drop the built-in one; rename your own.
+- `Protected action '<name>' requires its matching authentication descriptor` thrown by `make` or `layer` in plain JavaScript, a `No overload matches this call` at `make` in TypeScript: the binding holds a protected action and names no descriptor, or one of another identity. Give `{ authentication: Login }`.
+- `ActionRpc serves a protocol speaking JSON: ...`, a defect when `layer` builds: the host provides another serialization. Provide a JSON one, on the client too.
+- A type error on `middleware` naming `"Layer middleware fails only with the binding's errors and needs no client"`: a middleware declares an error neither the binding nor the built-ins hold, or is `requiredForClient`. Add the error to the binding's `error`, or check in the handler, declaring the error on its actions.
+- `Provider<CurrentMember, "live-rpc.Login">` among the requirements of `ActionRpc.layer`: the layer serves a protected action, and its authentication provider is not provided. Provide it, `Layer.provide(authenticate)`.
+- `Type 'HttpRouter' is not assignable to type 'never'` where the server is launched: an rpc protocol adds its route to the router, so it belongs inside what `HttpRouter.serve` serves, and here it was provided around `HttpRouter.serve`. Provide the protocol to the rpc layer.
+- `HttpRouter` owed by an `ActionRpc.layer` over stdio or a socket server: its authentication provider publishes a `protectedResource`, on a router those protocols lack. Give the provider serving that protocol no `protectedResource`.
+- `Request<"Requires", X>` owed by an `ActionRpc.layer` over stdio or a socket server though no handler yields `X`: the verifier yields `X`, which only a router-mounted protocol's route provides. Read `X` in the verifier's build, or serve the protected actions over HTTP or a WebSocket.
+- `Request<"Requires", X>` in the type of `ActionRpc.layer`, or `X` not assignable to `never` where the server is launched: a handler or the authorizer yields `X`, which nothing provides per request. A startup layer of `X` does not count, nor a middleware in a list not written as a tuple, nor one listed before a middleware requiring `X`: the first listed is innermost. List a middleware providing `X`, or provide `X` with router middleware around the layer. Where `X` is the identity, a middleware requires it on a layer serving a public action: bind the protected actions alone, or read the identity with `Effect.serviceOption`.
+- `Unauthenticated` `A bearer token is required.` from a browser's WebSocket though the page has a token: a browser WebSocket sets no header on its upgrade, so a token meant for the upgrade is never sent. Send the token on each message, with `RpcClient.withHeaders`.
+- A call dies with `Unknown request tag: <name>`: no layer serves the action, for which the client has a method all the same, or two `ActionRpc.layer`s were given one protocol, and only one receives its messages. Serve every rpc of a protocol from one layer; a second layer needs a protocol of its own, on another path.
+- A call dies with `Internal server error`: a defect, an undeclared failure, a middleware that throws, or a success or a declared failure that does not encode. The cause is in the server's logs and error reporters.
+- `RpcClientError` from every call, Effect's own error: the client could not reach the server. Check the client's protocol, URL and path against the server's.