# One program can replace several tool calls

> For agents: start with the [agent guide](https://ratstack.sh/llms.txt). Every page is Markdown by default; add `Accept: text/html` for HTML.

New on /news: [Foldkit 0.171.0 requires result Message schemas](/news).

A capability is a named action with a typed contract and a handler.
Code mode combines calls to those actions in one program.
MCP (Model Context Protocol) lets an agent discover and call tools.

ratstack.sh already offers code mode:

- `POST /api/execute`.
- The MCP `execute` tool.

One request runs an async function body that combines content calls. [Joel's reply](https://x.com/joelhooks/status/2106018556496457773) asks for this alongside CLI, API, and MCP.

## A live program

This program runs against the live HTTP endpoint.

The callable definitions are in [`apps/mischief/src/capabilities/index.ts` at `445b1a20b51a5492f8e586daeb9306e8011b7673`, lines 34–45](https://github.com/joelhooks/rat-stack/blob/445b1a20b51a5492f8e586daeb9306e8011b7673/apps/mischief/src/capabilities/index.ts#L34-L45). We wrote this read-only request.

```js
const found = await tools.search({ query: "cartridges", limit: 1 });
const page = await tools.read({ id: found.matches[0].id });
const graph = await tools.backlinks({ slug: page.routePath.split("/").at(-1) });
return { title: page.title, id: page.id, links: graph.backlinks.length };
```

The program passes the search result directly to read and reduces the graph result before returning it.

`POST /api/execute` returned this response on 2026-10-02:

```json
{"logs":[],"result":{"title":"Cartridges","id":"ratstack://lore/cartridges","links":31}}
```

The [cartridges page](/lore/cartridges) is now titled "A cartridge owns one job and its resources", so a fresh run returns that title.

Three typed calls use one outer request. This run measures neither latency nor token savings.

## The sandbox preserves the boundary

[`apps/site/src/capabilities/index.ts`](https://github.com/joelhooks/rat-stack/blob/main/apps/site/src/capabilities/index.ts) builds `toExecuteCapability(contentCapabilities)`. That list contains search, read, backlinks, neighbors, mentions, and path.

`joinInterest` belongs to the outer API/MCP registry. It does not belong to the sandbox's callable list.

[`packages/capability/src/to-code-mode.ts`](https://github.com/joelhooks/rat-stack/blob/main/packages/capability/src/to-code-mode.ts) builds the catalog and TypeScript declarations. Every call from sandbox code returns to application code that validates input and runs the handler.
That code encodes the output or declared failure.

[`sandbox-worker-loader.ts`](https://github.com/joelhooks/rat-stack/blob/main/apps/site/src/sandbox-worker-loader.ts) runs a fresh Dynamic Worker, a Worker loaded to execute sandbox code, with:

- No outbound network.
- A 100 ms CPU limit.
- Five subrequests.
- A ten-second timeout.

Imports, exports, and fetch are unavailable.

The [HTTP and MCP rate-limit checks](https://github.com/joelhooks/rat-stack/blob/main/apps/site/src/app.ts) use [native rate limits](https://github.com/joelhooks/rat-stack/blob/main/apps/site/src/rate-limits.ts):

- Six execute calls per IP per minute.
- 300 execute calls total per minute.
- Separate counters in each Cloudflare location.

Combining calls does not waive these limits.

Use the [agent guide](/llms.txt) for the endpoint and call format. See [MCP](/lore/mcp-is-another-surface) for the tool transport.

See [how we do it with Effect](/lore/how-we-do-it-with-effect) for the whole path.

## Sources

1. [Joel Hooks on code mode](https://x.com/joelhooks/status/2106018556496457773)
   Primary source. Joel Hooks on code mode Accessed 2026-10-02.

2. [apps/site/src/capabilities/index.ts](https://github.com/joelhooks/rat-stack/blob/main/apps/site/src/capabilities/index.ts)
   GitHub. apps/site/src/capabilities/index.ts Accessed 2026-10-02.

3. [packages/capability/src/to-code-mode.ts](https://github.com/joelhooks/rat-stack/blob/main/packages/capability/src/to-code-mode.ts)
   GitHub. packages/capability/src/to-code-mode.ts Accessed 2026-10-02.

4. [apps/site/src/sandbox-worker-loader.ts](https://github.com/joelhooks/rat-stack/blob/main/apps/site/src/sandbox-worker-loader.ts)
   GitHub. apps/site/src/sandbox-worker-loader.ts Accessed 2026-10-02.

5. [apps/site/src/app.ts](https://github.com/joelhooks/rat-stack/blob/main/apps/site/src/app.ts)
   GitHub. apps/site/src/app.ts Accessed 2026-10-02.

6. [Worker sandbox composition](https://github.com/joelhooks/rat-stack/blob/main/apps/site/src/worker.ts)
   GitHub. Provides the Worker Loader with sandboxLimits. Accessed 2026-10-02.

7. [Native execute rate limits](https://github.com/joelhooks/rat-stack/blob/main/apps/site/src/rate-limits.ts)
   GitHub. Six per IP and 300 global per minute. Accessed 2026-10-02.

8. [Code mode HTTP endpoint documentation](https://ratstack.sh/llms.txt#run-code-one-program-instead-of-several-calls)
   ratstack.sh. Documents POST /api/execute. The program below was observed on 2026-10-02. Accessed 2026-10-02.

## Lore on this page

- [MCP is another surface](/lore/mcp-is-another-surface)
- [A cartridge owns one job and its resources](/lore/cartridges)
- [Workers answer requests; Durable Objects own named state](/lore/workers-answer-requests-durable-objects-own-named-state)
- [Timeouts bound waiting](/lore/timeouts-bound-waiting)

## Linked from

- Agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms.txt)

- An MCP your users want → Rhys Sullivan's practical guide gives rat-stack a checklist for useful MCP tools. → [Read page](https://ratstack.sh/lore/an-mcp-your-users-want)

- Build and run rat-stack (README.md) → What is in the repo, how the example works, and how to run it. → [Read page](https://ratstack.sh/README.md)

- Capabilities → Named application actions exposed through generated interfaces share one definition and one server-side implementation. → [Read page](https://ratstack.sh/systems/capabilities)

- Change log → What changed in the files served here, newest first. → [Read page](https://ratstack.sh/log)

- Effect keeps the surfaces on one contract → Schema owns values, projections build interfaces, and Layers supply implementations. → [Read page](https://ratstack.sh/lore/how-we-do-it-with-effect)

- Full agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms-full.txt)

- Hexagonal architecture → Ports name the application's jobs; adapters connect them to the outside world. → [Read page](https://ratstack.sh/lore/hexagonal-architecture)

- Hosted agent interfaces → Discovery documents, HTTP, MCP, A2A, and bounded code mode expose the public reference to agents. → [Read page](https://ratstack.sh/systems/agent-front-door)

- Infrastructure as effects → Sam Goodwin relates application operations to infrastructure requirements in one typed program. → [Read page](https://ratstack.sh/lore/infrastructure-as-effects)

- keep-or-cut → Learn which pieces depend on each other, then keep only the ones your project needs. → [Read page](https://ratstack.sh/skills/keep-or-cut)

- learn-rat-stack → Trace a capability through Effect, XState, five projections, the CLI, and Alchemy. Try hosted search and read. → [Read page](https://ratstack.sh/skills/learn-rat-stack)

- MCP is another surface → MCP lists and calls schema-typed tools; rat-stack projects the same handlers instead of adding MCP-only behavior. → [Read page](https://ratstack.sh/lore/mcp-is-another-surface)

- One capability, every surface → A schema-typed contract and one handler feed every interface rat-stack keeps. → [Read page](https://ratstack.sh/lore/one-capability-every-surface)

- One schema, three surfaces → A capability contract feeds CLI, HTTP, and MCP; OpenAPI is generated output, not their input. → [Read page](https://ratstack.sh/lore/one-schema-three-surfaces)

- Rat Stack lore | rat-stack → Short, source-grounded notes on the ideas and decisions behind rat-stack. → [Read page](https://ratstack.sh/lore)

- Rat Stack systems | rat-stack → The systems rat-stack ships, the standard each keeps, and how to check it. → [Read page](https://ratstack.sh/systems)

- Schema projections: 2026-09-18 history → Historical Effect rc.115 proposal and implementation receipts from 2026-09-18; use the one-capability-every-surface lore page for the current pattern. → [Read page](https://ratstack.sh/resources/schema-projections-and-code-mode)

- Source change history (log.md) → The generated change log as Markdown. → [Read page](https://ratstack.sh/log.md)

- The rat-stack bestiary eats excuses → A field guide to eight documented rat-stack creatures, with real habitats, enforceable behaviour, and strictly imaginary temperaments. → [Read page](https://ratstack.sh/lore/shitrat-bestiary)

- The war stories → Seven public repo incidents: a deploy undoes itself, failure says 200, sessions forget their guests, and the rat tests the demolition instructions. → [Read page](https://ratstack.sh/lore/shitrat-war-stories)

- use-a-prompt → Discover and read published rat-stack prompts before starting a task with one. → [Read page](https://ratstack.sh/skills/use-a-prompt)

## Unlinked mentions

- [Agent rules for rat-stack (AGENTS.md)](https://ratstack.sh/AGENTS.md) → CLI, HTTP, MCP, RPC, and code mode are projections in packages/capability.

- [An MCP your users want](https://ratstack.sh/lore/an-mcp-your-users-want) → Keep code mode out of the default MCP tool list.: rat-stack today: CLI mcp uses plain tools; --code-mode opts into code mode.

- [Build and run rat-stack (README.md)](https://ratstack.sh/README.md) → No code mode:

- [Capabilities](https://ratstack.sh/systems/capabilities) → The hosted registry includes content search and graph traversal, flags, prompts, CAFE news and profiles, learning, code mode, and joinInterest.

- [keep-or-cut](https://ratstack.sh/skills/keep-or-cut) → Cutting MCP therefore cuts code mode too; apply both lists.¶

- [Schema projections: 2026-09-18 history](https://ratstack.sh/resources/schema-projections-and-code-mode) → MCP surface: execute (code mode), skills (server-side guides for the model), tools search / describe / call, plus artifacts.
