@gjermundgaraba/effect-actions 0.14.0 → 0.15.0

package/dist/mcp/client.d.mts

@@ -0,0 +1,87 @@
+import { BuiltIn } from "../contract/errors.mjs";
+import { Call } from "../contract/call.mjs";
+import { Action_d_exports, Any } from "../Action.mjs";
+import { Any as Any$1, VerifierError } from "../authentication/provider.mjs";
+import { Effect, Schema } from "effect";
+import { Headers, HttpClient, HttpClientError, HttpClientRequest } from "effect/http";
+//#region src/mcp/client.d.ts
+/**
+ * An MCP request's parameters, as `request` takes them: JSON, with any `_meta`, leaving
+ * out an `undefined` one, as a caller may. A helper passing on whole params types them as this,
+ * and a tool's `arguments` as `Schema.Json`, never `unknown`.
+ */
+export interface Params {
+  readonly _meta?: {
+    readonly [key: string]: Schema.Json;
+  };
+  readonly [key: string]: Schema.Json | undefined;
+}
+/** Where `client` sends, through what client, and what the endpoint's authentication declares. */
+export interface ClientOptions<D extends Any$1 | undefined = Any$1 | undefined> {
+  /**
+   * The endpoint, resolved by the `HttpClient`: relative under `Testing.layer`. Defaults to `/mcp`,
+   * the default `layerHttp` path.
+   */
+  readonly url?: string;
+  /**
+   * Wraps the native `HttpClient`, as `ActionHttp.client` takes it: a bearer token is
+   * `HttpClient.mapRequest(HttpClientRequest.bearerToken(token))`.
+   */
+  readonly transformClient?: (client: HttpClient.HttpClient) => HttpClient.HttpClient;
+  /**
+   * The endpoint's descriptor, as `layerHttp` takes it: an error its verifier declares, the
+   * endpoint's HTTP answer for a protected tool, is then that error's decoded value, as over
+   * `ActionHttp.client`.
+   */
+  readonly authentication?: D;
+}
+/** Where a `request` goes, and with what headers. */
+export interface RequestOptions {
+  /**
+   * The endpoint, resolved by the `HttpClient` that sends the request: relative under `Testing.layer`.
+   * Defaults to `/mcp`, as `client`'s does; converting to a web `Request` needs an absolute
+   * one.
+   */
+  readonly url?: string;
+  readonly headers?: Headers.Input;
+}
+declare const McpCallError_base: Schema.Class<McpCallError, Schema.TaggedStruct<"McpCallError", {
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * An answer a client method cannot read as the action's success or a declared error, such as
+ * the native server's message for invalid arguments or an unknown tool, or a result without
+ * its structured content. Its message holds the answer. Structured content that does not
+ * decode as the success is a `SchemaError` instead, and a request that fails an
+ * `HttpClientError`.
+ */
+export declare class McpCallError extends McpCallError_base {}
+type CallError<A extends Any, D> = A["error"][number]["Type"] | VerifierError<A, D>["Type"] | BuiltIn | Schema.SchemaError | HttpClientError.HttpClientError | McpCallError;
+/** Every action of `Actions` as `client.<action>(input)`, calling its tool. */
+export type Client<Actions extends ReadonlyArray<Any>, D = undefined> = { readonly [A in Actions[number] as A["name"]]: Call<A, Effect.Effect<A["success"]["Type"], CallError<A, D>>>; };
+/**
+ * A client of an MCP endpoint served by `layerHttp`, one method per action calling
+ * its tool with one stateless request, as `ActionHttp.client` calls routes: the input is
+ * encoded with the action's schema, and the success decoded from its structured content, each
+ * media field from the blocks whose `_meta` names it, and a success that is media, or whose
+ * every field is, from its blocks alone. A declared error the tool returns, the action's own
+ * or a refusal, is its decoded value, and so is a refusal the endpoint's authentication
+ * answers with, or an error its verifier declares, given the `authentication`: a test telling a 401 or 403 from a tool result asserts the status of a request
+ * `request` builds. The argument may be omitted when `{}` is a valid input. Requires the
+ * native `HttpClient`, such as the one `Testing.layer` provides.
+ */
+export declare function client<const Actions extends ReadonlyArray<Any>, D extends Any$1 | undefined = undefined>(actions: Actions, options?: ClientOptions<D>): Effect.Effect<Client<Actions, D>, never, HttpClient.HttpClient>;
+/**
+ * One stateless MCP request of `method` with `params`, as `layerHttp` serves it,
+ * as the native request value: the JSON-RPC envelope, the 2026-07-28 headers (`Accept`,
+ * `MCP-Protocol-Version`, `MCP-Method`), `mcp-name` from
+ * `params.uri` for `resources/read` and `params.name` otherwise, and the client metadata in
+ * `_meta` are filled in, under any `_meta` given, such as a `progressToken`; the protocol
+ * version is always the request's own. The test sends it: `HttpClient.execute` answers the
+ * response as the endpoint sent it, whatever its status, and `HttpClientRequest.toWebResult`
+ * gives the web `Request` a web handler or `fetch` takes, once `url` is absolute. It is for a test
+ * asserting on what `client` decodes away, such as `tools/list`, a refusal's challenge, or
+ * a call its types would not send.
+ */
+export declare const request: (method: string, params?: Params, { headers, url }?: RequestOptions) => HttpClientRequest.HttpClientRequest;
+//#endregion

package/dist/mcp/client.mjs

@@ -0,0 +1,122 @@
+import { Refusal } from "../contract/errors.mjs";
+import { Anyone, assertOnce, projectedErrors } from "../contract/rules.mjs";
+import { checked } from "../contract/call.mjs";
+import { defaultPath, httpProtocol, liftOf, unliftedFrom } from "./protocol.mjs";
+import { Effect, Option, Predicate, Schema, identity } from "effect";
+import { McpSchema } from "effect/ai";
+import { HttpClient, HttpClientRequest } from "effect/http";
+import { Sse } from "effect/encoding";
+//#region src/mcp/client.ts
+/**
+* One stateless MCP request of `method` with `params`, as `layerHttp` serves it: the headers
+* routing it, which repeat what its body says, and its JSON-RPC body. The client metadata goes in
+* `_meta`, under any given, such as a `progressToken`; the protocol version is always the
+* request's own.
+*/
+const statelessRequest = (method, params) => {
+	const { protocolVersion } = httpProtocol;
+	const name = method === "resources/read" ? params.uri : params.name;
+	return {
+		headers: {
+			accept: "application/json, text/event-stream",
+			"mcp-protocol-version": protocolVersion,
+			"mcp-method": method,
+			...Predicate.isString(name) ? { "mcp-name": name } : {}
+		},
+		body: {
+			jsonrpc: "2.0",
+			id: 1,
+			method,
+			params: {
+				...params,
+				_meta: {
+					"io.modelcontextprotocol/clientCapabilities": {},
+					"io.modelcontextprotocol/clientInfo": {
+						name: "effect-actions",
+						version: "0"
+					},
+					...params._meta,
+					"io.modelcontextprotocol/protocolVersion": protocolVersion
+				}
+			}
+		}
+	};
+};
+/**
+* An answer a client method cannot read as the action's success or a declared error, such as
+* the native server's message for invalid arguments or an unknown tool, or a result without
+* its structured content. Its message holds the answer. Structured content that does not
+* decode as the success is a `SchemaError` instead, and a request that fails an
+* `HttpClientError`.
+*/
+var McpCallError = class extends Schema.TaggedError()("McpCallError", { message: Schema.String }) {};
+const textOf = (block) => block?.type === "text" ? block.text : void 0;
+const ToolCallReply = Schema.Union([Schema.Struct({ result: McpSchema.CallToolResult }), Schema.Struct({ error: Schema.Struct({
+	code: Schema.Finite,
+	message: Schema.String
+}) })]);
+const decodeReply = Schema.decodeUnknownOption(Schema.fromJsonString(ToolCallReply));
+const replyOf = (response, text) => {
+	if (!(response.headers["content-type"] ?? "").startsWith("text/event-stream")) return decodeReply(text);
+	const data = [];
+	Sse.makeParser((event) => {
+		if (Predicate.isTagged(event, "Event")) data.push(event.data);
+	}).feed(text);
+	return Option.fromNullishOr(data.flatMap((message) => Option.toArray(decodeReply(message))).at(-1));
+};
+const failWith = (errors, text, otherwise) => Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.toCodecJson(Schema.Union(errors))))(text).pipe(Effect.mapError(() => otherwise), Effect.flatMap(Effect.fail));
+const callTool = (client, url, action, lift, refusedWith, input) => {
+	const { name } = action;
+	const other = (answer) => new McpCallError({ message: `MCP tools/call "${name}" ${answer}` });
+	return Effect.gen(function* () {
+		const encoded = yield* Schema.encodeEffect(Schema.toCodecJson(action.input))(input);
+		const response = yield* client.execute(request("tools/call", {
+			name,
+			arguments: encoded
+		}, { url }));
+		const text = yield* response.text;
+		if (response.status !== 200) return yield* failWith(refusedWith, text, other(`answered ${response.status}: ${text}`));
+		const reply = replyOf(response, text);
+		if (Option.isNone(reply)) return yield* Effect.fail(other(`had no reply: ${text}`));
+		if ("error" in reply.value) {
+			const { code, message } = reply.value.error;
+			return yield* Effect.fail(other(`failed with ${code}: ${message}`));
+		}
+		const { result } = reply.value;
+		if (result.isError === true) {
+			const error = textOf(result.content.find((block) => block.type === "text")) ?? "";
+			return yield* failWith(projectedErrors(action), error, other(`returned an error: ${error}`));
+		}
+		if (result.structuredContent === void 0 && lift.rest !== void 0) return yield* Effect.fail(other(`returned no structured content: ${text}`));
+		return yield* Schema.decodeUnknownEffect(Schema.toCodecJson(action.success))(unliftedFrom(lift, result));
+	});
+};
+function client(actions, { url = defaultPath, transformClient = identity, authentication } = {}) {
+	assertOnce("action", actions);
+	return Effect.map(HttpClient.HttpClient, (native) => {
+		const http = transformClient(native);
+		return Object.fromEntries(actions.map((action) => {
+			const lift = liftOf(action.success);
+			const refusedWith = [...Refusal.members, ...action.caller === Anyone ? [] : authentication?.error ?? []];
+			return [action.name, checked(action, (input) => callTool(http, url, action, lift, refusedWith, input))];
+		}));
+	});
+}
+/**
+* One stateless MCP request of `method` with `params`, as `layerHttp` serves it,
+* as the native request value: the JSON-RPC envelope, the 2026-07-28 headers (`Accept`,
+* `MCP-Protocol-Version`, `MCP-Method`), `mcp-name` from
+* `params.uri` for `resources/read` and `params.name` otherwise, and the client metadata in
+* `_meta` are filled in, under any `_meta` given, such as a `progressToken`; the protocol
+* version is always the request's own. The test sends it: `HttpClient.execute` answers the
+* response as the endpoint sent it, whatever its status, and `HttpClientRequest.toWebResult`
+* gives the web `Request` a web handler or `fetch` takes, once `url` is absolute. It is for a test
+* asserting on what `client` decodes away, such as `tools/list`, a refusal's challenge, or
+* a call its types would not send.
+*/
+const request = (method, params = {}, { headers = {}, url = defaultPath } = {}) => {
+	const { headers: routingHeaders, body } = statelessRequest(method, params);
+	return HttpClientRequest.post(url).pipe(HttpClientRequest.setHeaders(headers), HttpClientRequest.setHeaders(routingHeaders), HttpClientRequest.bodyJsonUnsafe(body));
+};
+//#endregion
+export { McpCallError, client, request, statelessRequest };

package/dist/mcp/protocol.mjs

@@ -2,6 +2,7 @@ import { unsuspended } from "../contract/rules.mjs";
 import { Media, isMarked, kindOf } from "../contract/media.mjs";
 import { Predicate, Schema, SchemaAST } from "effect";
 import { McpProtocol } from "effect/ai";
+import { Base64 } from "effect/encoding";
 //#region src/mcp/protocol.ts
 const httpProtocol = McpProtocol.v2026_07_28;
 const protocols = [
@@ -10,42 +11,6 @@ const protocols = [
 	McpProtocol.v2025_06_18
 ];
 const defaultPath = "/mcp";
-const mcpNameHeaderOf = (method, params) => method === "resources/read" ? params.uri : params.name;
-/**
-* One stateless MCP request of `method` with `params`, as `ActionMcp.layerHttp` serves it:
-* the headers routing it, which repeat what its body says, and its JSON-RPC body. The client
-* metadata goes in `_meta`, under any given, such as a `progressToken`; the protocol version
-* is always the request's own.
-*/
-const statelessRequest = (method, params) => {
-	const { protocolVersion } = httpProtocol;
-	const name = mcpNameHeaderOf(method, params);
-	return {
-		headers: {
-			accept: "application/json, text/event-stream",
-			"mcp-protocol-version": protocolVersion,
-			"mcp-method": method,
-			...Predicate.isString(name) ? { "mcp-name": name } : {}
-		},
-		body: {
-			jsonrpc: "2.0",
-			id: 1,
-			method,
-			params: {
-				...params,
-				_meta: {
-					"io.modelcontextprotocol/clientCapabilities": {},
-					"io.modelcontextprotocol/clientInfo": {
-						name: "effect-actions",
-						version: "0"
-					},
-					...params._meta,
-					"io.modelcontextprotocol/protocolVersion": protocolVersion
-				}
-			}
-		}
-	};
-};
 const fieldKey = "effect-actions/field";
 const isMedia = Schema.is(Media);
 const isMediaArray = Schema.is(Schema.Array(Media));
@@ -145,5 +110,28 @@ const liftedFrom = (lift, success) => lift.fields.flatMap(({ name, kind, many })
 		value: media
 	}));
 });
+const mediaOf = ({ name, kind, many }, result) => {
+	const values = result.content.flatMap((block) => block.type === kind && block._meta?.["effect-actions/field"] === name ? [{
+		data: Base64.encode(block.data),
+		mimeType: block.mimeType
+	}] : []);
+	return many || values.length > 1 ? values : values[0];
+};
+/**
+* The encoded success a tool result carries, `liftedFrom` undone: its structured content, each
+* lifted field from the blocks whose `_meta` names it, and a success that is media from its
+* blocks alone.
+*/
+const unliftedFrom = (lift, result) => {
+	const [whole] = lift.fields;
+	if (whole !== void 0 && whole.name === void 0) return mediaOf(whole, result);
+	const { structuredContent = {} } = result;
+	if (!Predicate.isObject(structuredContent)) return structuredContent;
+	const lifted = new Set(lift.fields.map(({ name }) => name));
+	return Object.fromEntries([...Object.entries(structuredContent).filter(([key]) => !lifted.has(key)), ...lift.fields.flatMap((field) => {
+		const value = mediaOf(field, result);
+		return field.name === void 0 || value === void 0 ? [] : [[field.name, value]];
+	})]);
+};
 //#endregion
-export { defaultPath, fieldKey, httpProtocol, isMisplaced, liftOf, liftedFrom, protocols, statelessRequest };
+export { defaultPath, fieldKey, httpProtocol, isMisplaced, liftOf, liftedFrom, protocols, unliftedFrom };

package/docs/Action.md

@@ -29,7 +29,7 @@ Import `@gjermundgaraba/effect-actions/Action`.
 | `Action`, `Any`, `Implementation`              | Concrete and erased contracts, and bound implementations.    |
 | `AnyImplementation`, `AnyImplementation<A>`    | Any implementation, or any of actions `A`, erased.           |
 | `BuildServices`, `BuildError`                  | What builders read and fail with at startup.                 |
-| `implementation.actions`                       | Its exact contracts, as `Testing.mcpClient` takes them.      |
+| `implementation.actions`                       | Its exact contracts, as `ActionMcp.client` takes them.       |
 | `Handler`, `Handlers`, `Authorize`             | A typed handler, a list's record of them, and an authorizer. |
 | `Options`, `Mcp`                               | What `make` takes, and its `mcp` options.                    |
 
@@ -197,8 +197,8 @@ Derive the rule from `action.readOnly`, never from an `mcp` hint: changing an ac
 - **Name `scopes` in a `Forbidden` only where re-authorizing can grant them.** An OAuth
   challenge answers them, which a client follows only where the server publishes discovery
   ([Authentication.md](Authentication.md#publish-oauth-discovery)); with fixed tokens, such as
-  API keys, leave `scopes` out (it holds at least one: `scopes: []` is a type error). Without scopes it is a 403 over HTTP and, over MCP, an `isError` tool
-  result in a 200 ([guarantees.md](guarantees.md#wire-behavior)).
+  API keys, leave `scopes` out (it holds at least one: `scopes: []` is a type error). What a
+  refusal answers on each surface is in [guarantees.md](guarantees.md#wire-behavior).
 - **What a plain authorizer yields is a request-time requirement of every surface.** To read a
   store, make `authorize` an Effect that yields the store once and returns the function, as a
   builder does
@@ -225,8 +225,9 @@ failure compiles. What each surface answers is in [guarantees.md](guarantees.md#
 - **Fail with `Action.InvalidInput` for input that decodes but cannot be served**, naming
   `issues` of your own, instead of declaring a second error for bad input
   ([kitchen-sink/src/attachments/handlers.ts](../examples/kitchen-sink/src/attachments/handlers.ts)).
-- **For input you decode yourself**, such as a header or a route parameter, answer as the
-  surfaces do: `Schema.decodeUnknownEffect(schema)(value).pipe(Effect.mapError(Action.InvalidInput.fromSchemaError))`.
+- **For input you decode yourself** on the server, such as a header or a route parameter,
+  answer as the surfaces do, with every issue:
+  `Schema.decodeUnknownEffect(schema)(value, { errors: "all" }).pipe(Effect.mapError(Action.InvalidInput.fromSchemaError))`.
 - **Map another service's refusals before failing with them.** A client that decodes the
   built-in errors, such as `ActionHttp.client`, hands a handler that service's `Unauthenticated`
   or `Forbidden`. Passed on, it is this server's own refusal: a caller whose token is valid is

package/docs/ActionCli.md

@@ -148,9 +148,10 @@ In an aggregate, a command's options go under `commands`, keyed by the action's
 ### Add a command of your own
 
 Work every surface should offer, a bulk import for one, is an action first: a command of your
-own then only reads the file and calls it, as `notes import <file>` reads `Argument.FileText`
-and calls `importNotes`. For a syntax the options cannot express, such as a flag named apart
-from its field, build the command with native `Command.make`, `Flag` and `Argument`, and pass it
+own then only reads the file and calls it. Its client checks the input as it encodes it, naming
+a bad entry by its path, so a decode of your own only repeats that check. `notes import <file>`
+reads `Argument.FileText` and calls `importNotes`. For a syntax the options cannot express, such
+as a flag named apart from its field, build the command with native `Command.make`, `Flag` and `Argument`, and pass it
 in `subcommands`: `notes export <file>` takes `Argument.String("file")`
 ([notes-service/src/commands.ts](../examples/notes-service/src/commands.ts)):
 

package/docs/ActionMcp-failures.md

@@ -18,9 +18,10 @@ Search for a fragment of the message. The tasks are in [ActionMcp.md](ActionMcp.
 - A protected tool's call answers 401 to a signed-in client after a while: its token expired. The client refreshes it, or signs in again, on the challenge's `invalid_token`.
 - An MCP client gets an `isError` refusal, not the 401 or 403 it re-authorizes on: the handler sent a notification first, which starts the response, so its refusal is a tool result. Refuse in `authorize`.
 - A client that opens with `initialize` gets 401 where it lists the tools or calls a public one, on an endpoint that also serves protected tools: a session's every request authenticates. Sign the client in, or serve the public tools on an endpoint of their own.
+- A client that opens with `initialize`, such as Codex, gets 400 with JSON-RPC error `-32020`, `MCP-Protocol-Version header is required`, or 401 signed out where the endpoint serves a protected tool, and a `DELETE` gets 405: the endpoint is `requestScoped`, which speaks MCP 2026-07-28 alone and keeps no session. Connect that client to an endpoint without it, on a host that keeps a process running.
 - A request over HTTP answers 400, `MCP-Session-Id header is required; send initialize to start a session`: its `MCP-Protocol-Version` header is absent or names a 2025 revision, so it is a session's request, and it follows no `initialize`. One answering 404 names a session that ended, or one of a process since restarted: the client opens another.
-- A hand-written HTTP request answers 400 with JSON-RPC error `-32602`, `Required request metadata is missing` or `io.modelcontextprotocol/clientCapabilities request metadata is required`: it names 2026-07-28 in `MCP-Protocol-Version` and its `params._meta` lacks `io.modelcontextprotocol/protocolVersion`, for the first message, or `io.modelcontextprotocol/clientCapabilities`, for the second. Build it with `Testing.mcpRequest`, or copy the `curl` of [ActionMcp.md](ActionMcp.md#serve-tools-over-stdio).
-- A hand-written HTTP request answers 400 with JSON-RPC error `-32020`, `MCP-Protocol-Version header is required`, `Mcp-Method header does not match request method` or `Mcp-Name header does not match request parameters`: those headers repeat a 2026-07-28 request's revision, method and `tools/call` name, and one is absent or differs from its body. Build it with `Testing.mcpRequest`.
+- A hand-written HTTP request answers 400 with JSON-RPC error `-32602`, `Required request metadata is missing` or `io.modelcontextprotocol/clientCapabilities request metadata is required`: it names 2026-07-28 in `MCP-Protocol-Version` and its `params._meta` lacks `io.modelcontextprotocol/protocolVersion`, for the first message, or `io.modelcontextprotocol/clientCapabilities`, for the second. Build it with `ActionMcp.request`, or copy the `curl` of [mcp-tools](../examples/mcp-tools/README.md#connect-a-client).
+- A hand-written HTTP request answers 400 with JSON-RPC error `-32020`, `MCP-Protocol-Version header is required`, `Mcp-Method header does not match request method` or `Mcp-Name header does not match request parameters`: those headers repeat a 2026-07-28 request's revision, method and `tools/call` name, and one is absent or differs from its body. Build it with `ActionMcp.request`.
 - A hand-written HTTP request answers an empty 406: its `Accept` header does not list both `application/json` and `text/event-stream`, as `*/*` does not. Send both.
 - A client asking for 2025-03-26 or 2024-11-05 is offered 2025-11-25, and disconnects if it cannot speak it: HTTP and stdio serve 2026-07-28, 2025-11-25 and 2025-06-18. Update the client.
 - A request written by hand to a stdio server answers JSON-RPC error `-32602`, `Invalid request metadata`: it is neither preceded by `initialize` nor carries the 2026-07-28 metadata. Open with `initialize` and `notifications/initialized`, or give the request's `_meta` its `io.modelcontextprotocol/protocolVersion` and `io.modelcontextprotocol/clientCapabilities`.
@@ -29,3 +30,6 @@ Search for a fragment of the message. The tasks are in [ActionMcp.md](ActionMcp.
 - A disallowed `Origin` gets 401, not 403: the endpoint's authentication, which runs before its Origin check, refused the request.
 - Browser calls fail despite an allowed origin, the preflight answering 405, or 401 on an endpoint with `authentication`, which every method but `POST` meets first: `allowedOrigins` is no CORS. Add `HttpRouter.cors` ([browser clients](ActionMcp.md#allow-browser-clients)).
 - `Tool <name> has an output schema but did not return structured content` raised by a Python MCP client for an action that returns nothing: its success is sent as `null`, which a Python SDK release before the fix of python-sdk#3345 reads as missing. Update the SDK.
+- `MCP tools/call "<name>" answered 404`: the endpoint is not at `/mcp`, the default. Pass `ActionMcp.client` its `url`.
+- `MCP tools/call "<name>" returned an error: Invalid parameters for tool ...`: the endpoint serves another contract under that name. Pass `ActionMcp.client` the served contract value.
+- `UrlError` from `HttpClientRequest.toWebResult` or `toWeb` of an `ActionMcp.request`, or an `HttpClientError` whose reason is `InvalidUrlError` from a client method or a sent `ActionMcp.request`: the `url` is relative, such as the default `/mcp`, which only the `HttpClient` of `Testing.layer` resolves. Pass an absolute one.

package/docs/ActionMcp.md

@@ -18,7 +18,10 @@ Import `@gjermundgaraba/effect-actions/ActionMcp`.
 | `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 four for HTTP. |
+| `LayerHttpOptions`                    | Type of `layerHttp`'s options: `Options` and HTTP's own.    |
+| `client(actions, options?)`           | An Effect of a client calling each action's tool.           |
+| `request(method, params?, options?)`  | One MCP request, as the native `HttpClientRequest` to send. |
+| `McpCallError`                        | A client method's failure for an answer it cannot decode.   |
 
 `implementations` is one implementation or a list.
 
@@ -33,10 +36,15 @@ Import `@gjermundgaraba/effect-actions/ActionMcp`.
 | `path`                               | HTTP only: the endpoint's path; defaults to `/mcp`.        |
 | `allowedOrigins`                     | HTTP only: the exact origins allowed; none by default.     |
 | `allowSubscriptions`                 | HTTP only: `false` turns off 2026-07-28 subscriptions.     |
+| `requestScoped`                      | HTTP only: `true` runs a server per request.               |
 | `authentication`                     | HTTP only: the protected tools' authentication descriptor. |
 
-All but `actions`, `features` and `authentication` are Effect's own `McpServer` options, passed
-through. Its `protocols` and `allowSessionTermination` are not options.
+All but `actions`, `features`, `authentication` and `requestScoped` are Effect's own `McpServer`
+options, passed through. Its `protocols` and `allowSessionTermination` are not options.
+
+`client` takes `url`, default `/mcp`, `transformClient`, and the endpoint's `authentication`, so an
+error its verifier declares decodes; `request` takes `url` and `headers`.
+Types: `Client<Actions, D>`, `ClientOptions`, `RequestOptions`, `Params`.
 
 ## Serve tools over HTTP
 
@@ -66,6 +74,9 @@ see [Action-in-process.md](Action-in-process.md#share-one-build-across-servers).
   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.
+- **On a serverless host**, such as Cloudflare Workers, pass `requestScoped: true`: a server per
+  request, speaking 2026-07-28 alone with no session. Connect a client that opens with
+  `initialize` to a long-lived endpoint: [notes-service/src/worker.ts](../examples/notes-service/src/worker.ts).
 - 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)):
@@ -90,16 +101,9 @@ ActionMcp.runStdio([status, notes, identity], { name: "notes-service", version:
 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.
 
-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'
-```
+To try a server by hand, send one request as `request` builds it, its 2026-07-28 metadata in
+`_meta`: [mcp-tools](../examples/mcp-tools/README.md#connect-a-client) has the `curl`, with
+HTTP's five headers, and [notes-service](../examples/notes-service/README.md#run-it) the stdio command.
 
 - **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`
@@ -112,10 +116,7 @@ curl http://127.0.0.1:3000/mcp -d "$BODY" -H 'Content-Type: application/json' \
   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.
-- **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)).
+- **Test the tools without a process**: [Testing.md](Testing.md#test-mcp-tools).
 
 ## Describe tools to a model
 
@@ -156,8 +157,8 @@ 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.
+[mcp-tools/src/printers/Printers.ts](../examples/mcp-tools/src/printers/Printers.ts); `client`
+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
@@ -196,24 +197,22 @@ sign in. What a signed-in caller may do is each implementation's
   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`.
+- On a Bearer endpoint, a protected tool's step-up refusal answers the request, not a tool
+  result ([Authentication.md](Authentication.md#step-up-for-a-scope),
+  [guarantees.md](guarantees.md#wire-behavior)). 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).
+  origin is listed, so a page a user visits cannot call the tools; one without, as other
+  clients send, passes. Authentication runs first, so the verifier sees a token from any origin:
+  a request that must authenticate, or sends a token, gets 401 without a valid one. Read the
+  list from config: [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
@@ -224,9 +223,8 @@ A browser MCP client sends its page's `Origin`, and needs two things.
   [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:
+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
@@ -239,7 +237,6 @@ one and pass it as `features`:
 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,

package/docs/ActionToolkit-failures.md

@@ -6,7 +6,8 @@ The tasks are in [ActionToolkit.md](ActionToolkit.md).
 - An approved call never runs, and nothing is raised: a `tool-approval-response` finds its request by `approvalId` in the prompt history, and was sent without it. Use a `Chat`, or resend the assistant message holding the call and its request before the response.
 - `Type 'X' is not assignable to type 'never'` where a turn or a call by hand runs, or `Service not found` in plain JavaScript: a request service is provided around the turn, or around the whole call effect, not to the stream alone, and a protected tool owes its identity whatever its handler reads. A startup service's Layer is provided to `layer`.
 - A returned failure whose `result` is an `AiError` with reason `ToolParameterValidationError` (`failureOrigin: "parameters"`), not a declared error: the arguments did not decode. Neither `authorize` nor the handler ran.
-- A turn fails with an `AiError`, `Failed to encode result for tool '<name>'`: the handler failed with an error its action does not declare, which a cast or plain JavaScript lets through. Declare it on the action.
+- A call dies with the handler's failure and a `SchemaError` beside it: the handler failed with an error its action does not declare, which a cast or plain JavaScript lets through, or with one breaking a check of its schema, such as `Infinity` in a struct error's `Schema.Finite` field. Declare the error on the action, or fix the value.
+- A turn fails with an `AiError`, `Failed to encode result for tool '<name>'`: the handler's success does not encode, such as `Infinity` for a `Schema.Finite`.
 - A model reads base64 text where an image was meant: a tool's success holds an `Action.Image`, which a Toolkit gives the model as JSON text. Leave the action out of `actions`, or serve it over MCP, which sends an image block ([ActionMcp.md](ActionMcp.md#return-images-and-other-media)).
 - `Listed in actions, but no implementation holds it: <names>` thrown at `make`: those actions are not the implementations', by identity. `(another contract)` marks one whose name an implementation holds, as a second copy of the contracts module makes. Pass the implementation holding the action, or list the contract it implements.
 - `Duplicate tool: <name>` thrown at `make`: two implementations serve actions of one name. Rename one action; of two implementations of one contract, pass one.

package/docs/ActionToolkit.md

@@ -50,11 +50,11 @@ conversations.pipe(
 
 - **One `generateText` is one request to the model.** Its tool calls run, and their results come back in the response, unread by the model. For the model to read them, ask the `Chat` again with `prompt: []` while a response has `toolCalls` and no `tool-approval-request`.
 - Without `actions`, every action of the implementations is a tool, one added later included. Where a model must not get them all, list the tools ([Action.md](Action.md#define-a-contract)): [kitchen-sink/src/issues/assistant.ts](../examples/kitchen-sink/src/issues/assistant.ts).
-- A refusal or a declared error is not raised: it is a tool result with `isFailure: true`, which the model reads.
+- A refusal or a declared error is not raised: it is a tool result with `isFailure: true`, which the model reads. So are arguments that do not decode, an `AiError` (`ToolParameterValidationError`), not `InvalidInput`: neither `authorize` nor the handler ran.
 - A turn's tool calls, the approved calls of an answering turn included, run concurrently unless `generateText` is given a `concurrency`. A service they share must tolerate it: [assistant/src/tasks/store.ts](../examples/assistant/src/tasks/store.ts) locks each change.
 - Arguments the input does not declare are dropped, where HTTP and a CLI refuse them ([guarantees.md](guarantees.md#wire-behavior)): a misspelled optional argument is ignored silently.
 - Beside other tools, merge natively and provide every handler layer: `Toolkit.merge(toolkit, others)` with `Layer.mergeAll(layer, othersHandlers)`.
-- **A model loop behind a route.** Yield `toolkit` and the model in the implementation's builder, `Action.implement(Ask, Effect.map(toolkit, (tools) => (input) => ...))`: what the handler itself yields is owed per request. Provide `layer` to the route's layer, `ActionHttp.layer(Http, ask).pipe(Layer.provide(layer))`, not in the handler, so the tools share the routes' build ([Action-in-process.md](Action-in-process.md#share-one-build-across-servers)). A tool call runs as the request's caller, unless the handler provides another around it. Keep each caller's `Chat` in a service between requests ([kitchen-sink/src/assistant/conversations.ts](../examples/kitchen-sink/src/assistant/conversations.ts)), and answer an approval in a later one: [kitchen-sink/src/assistant/handlers.ts](../examples/kitchen-sink/src/assistant/handlers.ts), with a scripted model in [demo-model.ts](../examples/kitchen-sink/src/assistant/demo-model.ts), which the entrypoint provides through [kitchen-sink/src/memory.ts](../examples/kitchen-sink/src/memory.ts), and tested over HTTP in [kitchen-sink/test/assistant/assistant.test.ts](../examples/kitchen-sink/test/assistant/assistant.test.ts).
+- **A model loop behind a route.** Yield `toolkit` and the model in the implementation's builder, `Action.implement(Ask, Effect.map(toolkit, (tools) => (input) => ...))`: what the handler itself yields is owed per request. Provide `layer` to the route's layer, `ActionHttp.layer(Http, ask).pipe(Layer.provide(layer))`, not in the handler, so the tools share the routes' build ([Action-in-process.md](Action-in-process.md#share-one-build-across-servers)). A tool call runs as the request's caller, unless the handler provides another around it. Keep each caller's `Chat` in a service between requests ([kitchen-sink/src/assistant/conversations.ts](../examples/kitchen-sink/src/assistant/conversations.ts)), and answer an approval in a later one: [kitchen-sink/src/assistant/handlers.ts](../examples/kitchen-sink/src/assistant/handlers.ts), with a scripted model in [demo-model.ts](../examples/kitchen-sink/src/assistant/demo-model.ts), which the entrypoint provides through [kitchen-sink/src/memory.ts](../examples/kitchen-sink/src/memory.ts), and tested over HTTP in [kitchen-sink/test/assistant/assistant.test.ts](../examples/kitchen-sink/test/assistant/assistant.test.ts). Name the files as it does, the route's contract `Assistant.ts` and the loop `handlers.ts`, from the first one written: a lowercase `assistant.ts` beside the contract fails with TS1149 ([setup-failures.md](setup-failures.md)).
 - **The real model comes later?** Provide a scripted one from the entrypoint until then, as the kitchen-sink does. Reading the model with `Effect.serviceOption` hides the requirement: the server builds without one and every request fails.
 
 ### Call a tool by hand

package/docs/Authentication-failures.md

@@ -64,9 +64,9 @@ Tasks: [Authentication.md](Authentication.md),
   too ([ActionMcp.md](ActionMcp.md#protect-tools)).
 - A verifier's declared error arrives as 422: the error states no `httpApiStatus`. Give it the
   status it means, such as `{ httpApiStatus: 503 }`.
-- `Testing.mcpClient` fails with an `McpCallError`, not a typed error, when the verifier fails
+- `ActionMcp.client` fails with an `McpCallError`, not a typed error, when the verifier fails
   with an error its descriptor declares: over MCP that failure is the endpoint's HTTP answer,
-  before any tool runs. The `McpCallError` names its status and body.
+  before any tool runs. Pass the endpoint's descriptor as the client's `authentication`.
 - A route's `Cache-Control` is replaced by `no-store`: only a route's own answer keeps its
   caching, and this response is a failure that enclosing middleware serialized.
 

package/docs/Authentication.md

@@ -70,6 +70,12 @@ does an RPC binding ([live-rpc/src/Rpc.ts](../examples/live-rpc/src/Rpc.ts)).
   `ActionRpc.layer`, `ActionMcp.layerHttp` and `Authentication.protect` refuse, when they build,
   a descriptor that is another object than the one the provider was given, equal name and
   options or not.
+- Protecting an action that tests already call breaks them. An `Action.client` call then owes
+  `Type 'CurrentUser' is missing … from type 'Scope'`: provide the caller around each call
+  ([Testing-failures.md](Testing-failures.md)). A test that builds `ActionMcp.layerHttp` itself
+  gets `Property 'authentication' is missing`: serve `routes` with `Testing.layer`
+  ([ActionMcp-failures.md](ActionMcp-failures.md)). A call over HTTP without a credential gets
+  `Unauthenticated` at run time.
 - A local surface has no remote caller and takes no descriptor: the host provides the identity
   itself, for a CLI ([ActionCli.md](ActionCli.md#name-the-caller)), a Toolkit
   ([ActionToolkit.md](ActionToolkit.md#name-the-caller)) and an MCP server over stdio
@@ -142,15 +148,14 @@ added. The authorizer, a handler or the verifier may fail with one:
 
 - Step-up is a Bearer descriptor's, for protected actions and routes under `protect`: the
   refusal answers the request with 401 or 403 and its challenge, over MCP in place of the tool
-  result.
+  result unless the response has started ([guarantees.md](guarantees.md#wire-behavior)).
 - On a public action or under another scheme, an authorizer's or a handler's refusal is
   answered like a declared error, and RPC never steps up: a refusal is the call's typed failure
   ([guarantees.md](guarantees.md#wire-behavior)).
 - Name scopes only when re-authorizing can grant them: a server with fixed tokens, such as API
-  keys, leaves `scopes` out. A `Forbidden` without them prompts no login. Over HTTP it is a 403 without a
-  challenge. Over MCP it is an `isError` tool result, in a 200, from the authorizer or a
-  handler, and the endpoint's 403 only from the verifier
-  ([kitchen-sink/src/identity/authenticate.ts](../examples/kitchen-sink/src/identity/authenticate.ts)).
+  keys, leaves `scopes` out. A `Forbidden` without them prompts no login
+  ([kitchen-sink/src/identity/authenticate.ts](../examples/kitchen-sink/src/identity/authenticate.ts));
+  what it answers on each surface is in [guarantees.md](guarantees.md#wire-behavior).
 - Map another service's refusals before failing with them
   ([Action.md](Action.md#fail-with-declared-and-built-in-errors)): passed on, a `Forbidden`
   naming that service's scopes sends this server's caller to re-authorize for them.

package/docs/CONTEXT.md

@@ -23,7 +23,7 @@ page.
 - **Host**: the application that serves the surfaces: it builds their layers, provides their services and runs the server, subprocess or CLI.
 - **Surface**: where callers reach actions. A **remote surface** authenticates its callers (`ActionHttp.layer`, `ActionMcp.layerHttp`, `ActionRpc.layer`). A **local surface** has no one to authenticate (`ActionToolkit`, a local `ActionCli` command, `ActionMcp.runStdio`, `Action.client`): the host provides the identity.
 - **Binding**: what `ActionHttp.make` or `ActionRpc.make` returns: the actions its surface serves, as browser-safe data the server and every client share.
-- **Client**: one method per action, `client.<action>(input)`: `ActionHttp.client`, `ActionRpc.client`, `Testing.mcpClient` and, in process, `Action.client`.
+- **Client**: one method per action, `client.<action>(input)`: `ActionHttp.client`, `ActionRpc.client`, `ActionMcp.client` and, in process, `Action.client`.
 - **Authorizer**: `authorize`, a function of the called action that an implementation of protected actions states. It succeeds or fails with a refusal ([Action.md](Action.md#authorize-calls)).
 - **Authentication descriptor**: what `Authentication.make` returns: a named, browser-safe declaration of how a remote caller proves an identity. A binding or an MCP endpoint serving protected actions names it.
 - **Authentication provider**: what `Authentication.layer` returns for a descriptor, holding its **verifier**: the server-only function from a credential to the identity.

package/docs/Testing-failures.md

@@ -1,6 +1,9 @@
 # Testing failure modes
 
 What you see when something is wrong, and the fix. Search for a fragment of the message.
+A missing service's error can start
+`… with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined'`: search a line
+beneath it, `is missing the following properties from type 'Scope'`, instead.
 The tasks are in [Testing.md](Testing.md).
 
 - A route answers an empty 500, which a client method reports as `HttpClientError: Decode error (500 …)`: a defect, or a result that does not encode. `Testing.layer` logs the cause as an error on the process console, under `it.effect` too, and nothing for a request that succeeds or is refused: read the test's output, or collect it with a `Logger` or an `ErrorReporter` provided around the layer.
@@ -14,8 +17,5 @@ The tasks are in [Testing.md](Testing.md).
 - `Property '<field>' does not exist on type 'MethodError<Action<…>>'`, or on a built-in error, after `expect(error).toBeInstanceOf(…)`: `toBeInstanceOf` does not narrow the union of the action's errors. Compare with `toEqual(new X({ … }))`, or narrow with `instanceof` ([Assert on errors](Testing.md#assert-on-errors)).
 - A test passes whatever message an error carries: `toEqual` never compares a tagged error's `message`. Assert it separately ([Assert on errors](Testing.md#assert-on-errors)).
 - The test reads a service the handlers never changed: it was provided inside the routes and again to the test, two instances. Provide it once, around `Testing.layer`, with `Layer.provideMerge`.
-- `MCP tools/call "<name>" answered 404`: the endpoint is not at `/mcp`, the default. Pass `mcpClient` its `url`.
-- `MCP tools/call "<name>" returned an error: Invalid parameters for tool ...`: the endpoint serves another contract under that name. Pass `mcpClient` the served contract value.
 - A builder or handler fails with `NotFound: FileSystem.<method> (<path>)` for a file that exists, or a file route answers 500: with no `FileSystem` provided around `Testing.layer`, the routes read a no-op one. Provide `NodeFileSystem.layer` or `NodeServices.layer`. In a command test, the nearer of two provided is read: provide a fake `FileSystem` on the command, inside `NodeServices.layer`.
 - `Argument of type 'Layer<…, FileSystem | Generator | HttpPlatform | HttpRouter | Path>' is not assignable` at `HttpRouter.toWebHandler(routes)`: a web handler's routes need the platform services `Testing.layer(routes)` supplies itself. Provide `HttpServer.layerServices` to them.
-- `UrlError` from `HttpClientRequest.toWebResult` or `toWeb` of an `mcpRequest`, or an `HttpClientError` whose reason is `InvalidUrlError` from a client method or a sent `mcpRequest`: the `url` is relative, such as the default `/mcp`, which only the `HttpClient` of `Testing.layer` resolves. Pass an absolute one.