effect-actions

Define an Effect action once. Serve it over HTTP, MCP and Effect RPC, hand it to a model as a native Toolkit, and run it from a CLI. Same schemas, same handler, Effect's own servers and clients underneath.

If you are a coding agent, start at docs/README.md, not here, and read one page per tool call, again alone if its output says it was truncated. It routes every task, protecting an action and limiting request bodies included, to its page and its example.

Looks like this

A contract says what an action takes and answers, and who may call it:

import { Schema } from "effect";
import * as Action from "@gjermundgaraba/effect-actions/Action";

// A contract: what the action takes and answers, whether it changes anything, and who may
// call it. It imports no server code, so any client can import it, a browser page included.
export const Greet = Action.make("greet", {
  description: "Greet someone by name.",
  input: { name: Schema.String },
  success: Schema.String,
  readOnly: true,
  caller: Action.Anyone,
});

An implementation binds it to its handler:

import { Effect } from "effect";
import * as Action from "@gjermundgaraba/effect-actions/Action";
import { Greet } from "./Greeting.js";

// The implementation: the contract bound to its handler. Every surface takes this one value.
export const greeting = Action.implement(Greet, ({ name }) => Effect.succeed(`Hello, ${name}!`));

A binding gives it a route, for the server to serve and a client to call:

import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
import { Greet } from "./greeting/Greeting.js";

// The HTTP binding: `POST /api/greet`. The server serves it and the client calls it.
export const Http = ActionHttp.make([Greet]);

And the same implementation is served on every surface the host wants:

import { Layer } from "effect";
import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
import { Http } from "./Api.js";
import { greeting } from "./greeting/handlers.js";

// One implementation, two surfaces: a JSON route and an MCP tool at `/mcp`.
export const routes = Layer.mergeAll(
  ActionHttp.layer(Http, greeting),
  ActionMcp.layerHttp(greeting, { name: "greetings", version: "1.0.0" }),
);

Serve routes with Effect's HttpRouter.serve and a platform server, as examples/quickstart/src/server.ts does, and you have POST /api/greet and an MCP tool named greet at /mcp. The same greeting implementation is also:

const { toolkit, layer } = ActionToolkit.make(greeting); // native Effect AI Toolkit and its handler layer
const cli = ActionCli.make(greeting, { name: "greetings" }); // greetings greet --name Ada
const remote = ActionCli.remoteCommand(Http, Greet, { client: { baseUrl } }); // greet --name Ada, over HTTP
const local = Action.client(greeting); // the HTTP client's methods, in process
const rpc = ActionRpc.layer(ActionRpc.make([Greet]), greeting); // Effect RPC, on the protocol the host provides

And the client is Effect's own HttpApiClient, typed from the same contract, one method per action:

const greeting = Effect.gen(function* () {
  const client = yield* ActionHttp.client(Http, { baseUrl });

  return yield* client.greet({ name: "Ada" });
});

Why

• Input, success and errors are declared once. Routes, tools, CLI flags, clients and the OpenAPI document are derived from that declaration, so they cannot disagree.
• A handler can fail only with the errors its action declares and three built-in ones (400, 401, 403), and every client decodes them as typed values.
• Every contract states who may call it: caller: Action.Anyone, or the identity service a caller must have. A surface authenticates a protected action's request before decoding its input, with the provider the application builds from its own token verifier.
• Authorization is written once, on the implementation: Action.implement(actions, handlers, { authorize }), required for protected actions. Every surface runs it before each handler, and the rule reads the contract's readOnly instead of a hand-maintained list of mutation names.
• Public and protected routes share one binding, one OpenAPI document and one client, and a handler's startup services are built once per layer graph, however many surfaces serve it.
• The pieces are Effect's own: a native HttpApi, McpServer, RpcServer and RpcClient, with no SDK runtime dependency, so OpenAPI, Swagger, Scalar and HttpApiClient work unchanged.
• Tests run in memory: Action.client calls an implementation in process, and Testing.layer(routes) serves the routes and tools to typed clients without opening a port.

Install

pnpm add @gjermundgaraba/effect-actions effect@~4.0.4

It needs TypeScript 7 or newer and is ESM only (docs/setup.md). Add @effect/platform-node@~4.0.4 to serve or run a CLI from Node. Every module is a subpath import (.../Action, .../ActionHttp, ...); there is no package root, so a contracts-only bundle never loads a server.

Examples

examples/ holds complete applications, each a directory you can run, with its own tests, laid out the way we recommend for an application: a folder per domain, the contract in one file a browser can import, one entrypoint per way of running it. They are type-checked and tested with the library and ship in the package.

• quickstart: the program above.
• notes-service: a service with bearer authentication, a JSON API and MCP tools from one implementation, a CLI and a browser client. Most applications are this.
• mcp-tools: an MCP server whose tools wrap an upstream HTTP API.
• assistant: no server, the same implementations as a model's tools and as local commands.
• live-rpc: Effect RPC over a WebSocket.
• kitchen-sink: every module and nearly every option in one application, with an index from each to the file that shows it.

Docs

docs/ is written for coding agents: one short page per module, organized by task, each linking to the example files that show the task working.

• docs/README.md: start here: which page answers which task, and which surface to use for which caller.
• docs/guarantees.md: what each case looks like on the wire, on every surface, and what the library leaves to the application.
• docs/CONTEXT.md: the vocabulary the docs and the code use.

For agents

The effect-actions skill puts the docs in front of a coding agent. With the skills CLI, for any agent it supports:

npx skills add gjermundgaraba/effect-actions --skill effect-actions

As a Claude Code plugin:

/plugin marketplace add gjermundgaraba/effect-actions
/plugin install effect-actions@effect-actions-marketplace

As a Codex plugin:

codex plugin marketplace add gjermundgaraba/effect-actions
codex plugin add effect-actions@effect-actions-marketplace

The skill is generated from docs/ on the main branch, which can be ahead of the latest release. Its links to the examples are paths into the installed package, node_modules/@gjermundgaraba/effect-actions/examples, which an agent reads without a network; the pages of the installed version are beside them, in node_modules/@gjermundgaraba/effect-actions/docs.

Status

The effect peer admits the patches of the Effect release the package is tested against, since the modules the surfaces build on may change in a minor release (see docs/setup.md). Actions are unary JSON over HTTP, MCP and Effect RPC, whose protocols speak JSON alone: no streaming or uploads. Token verification and the authorization rule belong to the application; the library supplies the authentication descriptor and provider, runs the rule, and answers the refusals. See docs/guarantees.md.

Acknowledgements

A few ideas (like the native Toolkit and CLI projections) are inspired by the excellent rat-stack by Joel Hooks.

Contributing

The rules for changing the library are in AGENTS.md. MIT licensed.