# One schema, three surfaces

> 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).

[Joel writes in a reply](https://x.com/joelhooks/status/2106018556496457773):

> my approach wrt to the agentic backend is to cover cli/api/mcp with a single openapi schema that is used to generate all three

His example is this repository. A capability is a named action with a contract and handler.
A contract defines the shared input, output, failures, and metadata.
Effect Schema supplies types and runtime checks for these values.

The code makes the direction more precise:

- A capability contract owns Effect schemas.
- HttpApi, OpenAPI, CLI, and MCP derive from that contract.
- CLI and MCP do not consume the generated OpenAPI JSON.

Each interface for calling the action, or surface, shares the same behavior. [`defineContract`](https://github.com/joelhooks/rat-stack/blob/main/packages/capability/src/contract.ts) owns input, output, failure, description, and annotations. `implement` binds one handler.

A projection builds an interface from a capability.

## One contract feeds the projections

```text
Contract (Effect schemas + one handler)
├─ toHttpApi ── HTTP + OpenAPI
├─ toCommand ── CLI
└─ toToolkit ── MCP tools
```

- [to-http-api.ts](https://github.com/joelhooks/rat-stack/blob/main/packages/capability/src/to-http-api.ts) derives HttpApi endpoints, the handler Layer, and OpenAPI.
- [to-command.ts](https://github.com/joelhooks/rat-stack/blob/main/packages/capability/src/to-command.ts) derives flags or positional inputs, schema decoding, and the command handler.
- [to-toolkit.ts](https://github.com/joelhooks/rat-stack/blob/main/packages/capability/src/to-toolkit.ts) derives tool schemas, annotations, and the toolkit handler Layer.

## Where the CLI composes them

[`apps/cli/src/surfaces.ts`](https://github.com/joelhooks/rat-stack/blob/main/apps/cli/src/surfaces.ts) composes the projections. [`command.ts`](https://github.com/joelhooks/rat-stack/blob/main/apps/cli/src/command.ts) maps registered capabilities to commands. It also prints the generated OpenAPI document.

Source: [`apps/cli/src/surfaces.ts` at `b4d6b8f499e57bc76914ad70df3a0c99751ae28c`, lines 25–44](https://github.com/joelhooks/rat-stack/blob/b4d6b8f499e57bc76914ad70df3a0c99751ae28c/apps/cli/src/surfaces.ts#L25-L44).

apps/cli/src/surfaces.ts at b4d6b8f499e57bc76914ad70df3a0c99751ae28c; lines 25-33,40-44; highlighted none.

```typescript
export const capabilities = [
  ...coreCapabilities,
  ...learnCapabilities,
] as const;

export const cliCapabilities = [
  ...coreCapabilities,
  ...localLearnCapabilities,
] as const;
export const http = toHttpApi("RatStack", capabilities);

export const tools = toToolkit(cliCapabilities);

export const codeMode = toCodeMode(cliCapabilities);
```

HTTP uses stateless learning capabilities. MCP and code mode use local learning capabilities.
Both lists include the same core capabilities, including `inspectFile`.

One HttpApi definition supplies the HTTP implementation and its OpenAPI document. The broader shared definition is the capability contract. This split avoids three independently maintained schemas.

See [MCP](/lore/mcp-is-another-surface), [OpenAPI](/lore/openapi-describes-the-refusal-too), and [code mode](/lore/one-program-can-replace-several-tool-calls) for each interface.

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

## Sources

1. [Joel Hooks on schema-driven CLI/API/MCP](https://x.com/joelhooks/status/2106018556496457773)
   Primary source. Joel Hooks on schema-driven CLI/API/MCP Accessed 2026-10-02.

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

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

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

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

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

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

## Lore on this page

- [MCP is another surface](/lore/mcp-is-another-surface)
- [OpenAPI describes the refusal too](/lore/openapi-describes-the-refusal-too)
- [Capabilities](/systems/capabilities)
- [Schemas define the boundary](/lore/schemas-define-the-boundary)
- [One program can replace several tool calls](/lore/one-program-can-replace-several-tool-calls)

## Linked from

- A Layer as constructor → Sam Goodwin compares an Effect Layer that builds a service to a constructor. → [Read page](https://ratstack.sh/lore/layer-constructor-pattern)

- add-a-feature-flag → Declare a typed feature flag, its scoped evidence ladder, approval roles, removal date, and durable ledger adapter. → [Read page](https://ratstack.sh/skills/add-a-feature-flag)

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

- Auth → Email and password sign-in through Better Auth, with the signed-in person provided to each RPC call. → [Read page](https://ratstack.sh/systems/auth)

- 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)

- CAFE names the Cloudflare, Alchemy, Foldkit and Effect stack → CAFE is a named stack: Cloudflare runs the app, Alchemy declares it, Foldkit draws the UI, and Effect does the typed work. → [Read page](https://ratstack.sh/lore/cafe-stack)

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

- Database → One interface records action runs and their outcomes in either Cloudflare D1 or Postgres through Hyperdrive. → [Read page](https://ratstack.sh/systems/database)

- Effect + Alchemy peer patterns → Source-grounded patterns from repos on nearby Effect and Alchemy pins. → [Read page](https://ratstack.sh/resources/same-version-repos)

- 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)

- Feature flags → Typed feature flags with owners, removal dates, and stable subject rollouts. → [Read page](https://ratstack.sh/systems/flags)

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

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

- learn → Present Effect, Alchemy, XState, and application-design concepts during real work when the operator enables learn mode. Use for adaptive explanations and local learning progress. → [Read page](https://ratstack.sh/skills/learn)

- 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)

- OpenAPI describes the refusal too → The generated HTTP contract declares inputs, outputs, and the bodyless 400 returned when decoding fails. → [Read page](https://ratstack.sh/lore/openapi-describes-the-refusal-too)

- Oxlint rule limits → How the current lint rules draw their syntax boundaries. → [Read page](https://ratstack.sh/resources/lint-rule-limits)

- Purpose and boundaries of rat-stack (VISION.md) → What this starter is for and what a useful copy should keep. → [Read page](https://ratstack.sh/VISION.md)

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

- 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)

- Schemas define the boundary → Define accepted data with Schema, decode unknown input before dispatch, and encode results through the declared contract. → [Read page](https://ratstack.sh/lore/schemas-define-the-boundary)

- security-audit → Security guidance and vulnerability review for codebases, APIs, services, CLI tools, libraries, and daemons. Use for security questions, focused reviews, vulnerability research, security audits, or pen tests. Run the complete workflow only for explicit codebase audit or pen-test requests, full/comprehensive/end-to-end reviews, or requested report artifacts. → [Read page](https://ratstack.sh/skills/security-audit)

- Shared schemas need a transition period → Keep old and new representations usable while consumers migrate. → [Read page](https://ratstack.sh/lore/schema-changes-need-a-transition)

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

- 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

- [A cartridge owns one job and its resources](https://ratstack.sh/lore/cartridges) → A service is the named interface callers use for that job.

- [A clean playground](https://ratstack.sh/lore/a-clean-playground) → A service is a named interface for a job.

- [A Layer as constructor](https://ratstack.sh/lore/layer-constructor-pattern) → of({ … }) returns the methods, checked against the service interface.¶

- [A service captures its construction dependencies](https://ratstack.sh/lore/services-capture-dependencies) → A service is a named interface.

- [add-a-capability](https://ratstack.sh/skills/add-a-capability) → Do not write separate business logic for each interface.¶

- [add-a-lifecycle-machine](https://ratstack.sh/skills/add-a-lifecycle-machine) → A service is a named interface for one job.

- [add-a-store](https://ratstack.sh/skills/add-a-store) → A service is a named interface for one job.

- [Agent rules for rat-stack (AGENTS.md)](https://ratstack.sh/AGENTS.md) → Errors are part of the interface.

- [An MCP your users want](https://ratstack.sh/lore/an-mcp-your-users-want) → rat-stack today: Each interface uses the same contract and handler.

- [Analytics](https://ratstack.sh/systems/analytics) → A service is a named interface for one job.¶

- [Build and run rat-stack (README.md)](https://ratstack.sh/README.md) → WEB\_BOT\_AUTH\_ENABLED and WEB\_BOT\_AUTH\_PRIVATE\_JWK protect a different interface; do not remove them with account auth.

- [Capabilities](https://ratstack.sh/systems/capabilities) → A service is a named interface for one job.

- [Chris Tate](https://ratstack.sh/lore/chris-tate) → Generative UI is an interface assembled by a model from supplied components.¶

- [Code snippets quote a pinned source](https://ratstack.sh/lore/code-snippets) → A port is an application-owned interface.

- [Configuration is a supplied, validated dependency](https://ratstack.sh/lore/configuration-is-a-dependency) → A service is a named interface.

- [Database](https://ratstack.sh/systems/database) → A service is a named interface for one job.¶

- [Dependency injection is the reason to choose Effect](https://ratstack.sh/lore/dependency-injection-is-the-reason-to-choose-effect) → A service gives callers a typed interface.

- [Devtools](https://ratstack.sh/systems/devtools) → A service is a named interface for one job.¶

- [Effect + Alchemy peer patterns](https://ratstack.sh/resources/same-version-repos) → Capability fence: test or lint that every surface, including toRpc, originates from the capability registry; make the test prove its guarded paths exist and contain files.

- [Effect 4 study: September 2026](https://ratstack.sh/resources/effect-4-reference-projects) → t3code splits Services/ (tag + shape interface) from Layers/ (implementation) per module.

- [Effect basics](https://ratstack.sh/lore/effect-basics) → A service is a named interface for work.

- [Effect keeps the surfaces on one contract](https://ratstack.sh/lore/how-we-do-it-with-effect) → A projection builds an interface from a capability, a named action with a contract and handler.

- [Engine-neutral tokens keep adapters replaceable](https://ratstack.sh/lore/engine-neutral-tokens-keep-adapters-replaceable) → A highlighter port is an interface for highlighting code, independent of the chosen highlighting tool.

- [Fence](https://ratstack.sh/systems/fence) → A service is a named interface for one job.¶

- [HATEOAS](https://ratstack.sh/lore/hateoas) → Roy Fielding names it as one of REST’s four uniform-interface constraints in his dissertation, chapter 5, section 5.1.5.

- [Hexagonal architecture](https://ratstack.sh/lore/hexagonal-architecture) → A port is an interface for an application job.

- [HTTP success needs a status check and a decoder](https://ratstack.sh/lore/http-responses-need-validation) → An adapter implements an application interface for a provider.¶

- [Interest signup](https://ratstack.sh/systems/interest) → Call it through MCP, POST /api/joinInterest, or the command-line interface (CLI).

- [keep-or-cut](https://ratstack.sh/skills/keep-or-cut) → A projection builds a callable interface from capabilities.¶

- [Layer composition makes dependencies explicit](https://ratstack.sh/lore/layers-make-dependencies-explicit) → A service is a named interface.

- [learn](https://ratstack.sh/skills/learn) → If they are absent from MCP, report that feedback sign-in is unavailable on that surface.

- [Learn mode presents concepts at useful depths](https://ratstack.sh/systems/learn) → A service is a named interface for one job.¶

- [learn-alchemy](https://ratstack.sh/skills/learn-alchemy) → A service is a named interface for one job.

- [learn-rat-stack](https://ratstack.sh/skills/learn-rat-stack) → A service is a named interface for one job.

- [Lint and type escape ledger (debt.md)](https://ratstack.sh/debt.md) → Reason: This erased projection interface retains only the capability discriminator and its callable boundary.

- [One capability, every surface](https://ratstack.sh/lore/one-capability-every-surface) → A projection is code that converts registered capabilities into an interface.

- [One prompt serves people and agents](https://ratstack.sh/systems/prompts) → A projection builds a callable interface from capabilities.¶

- [Purpose and boundaries of rat-stack (VISION.md)](https://ratstack.sh/VISION.md) → Public GitHub is a steal-the-ideas surface, not a supported product.

- [rat-stack-mode](https://ratstack.sh/skills/rat-stack-mode) → md: changing an interface or user-visible behavior.¶

- [Run Effect at the integration boundary](https://ratstack.sh/lore/run-effect-at-the-boundary) → A service is a named interface.

- [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.

- [Schemas define the boundary](https://ratstack.sh/lore/schemas-define-the-boundary) → Derive the TypeScript type from the schema rather than maintaining a second interface.

- [ship](https://ratstack.sh/skills/ship) → CLI: command-line interface, a program called through terminal commands.¶

- [Structure an Effect codebase by domain](https://ratstack.sh/lore/structure-effect-by-domain) → A service is a named interface for that work.

- [test-behaviour](https://ratstack.sh/skills/test-behaviour) → An example test fits one interface between parts, such as a service over the real filesystem.

- [Tests prove behavior through supplied services](https://ratstack.sh/lore/tests-that-earn-their-place) → A service is a named interface.

- [uncomplect](https://ratstack.sh/skills/uncomplect) → Projection: An interface built from capabilities: a command, API, or agent tool.¶
