# MCP is another surface

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

The Model Context Protocol lets an agent client discover and call tools. The [tools specification](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) defines:

- `tools/list` for discovery.
- `tools/call` for calling a tool.
- Input JSON Schema.
- Optional output JSON Schema.

A client that speaks MCP can discover names and arguments without learning a separate call format. In rat-stack, MCP [projects the shared handler](/lore/one-schema-three-surfaces).

## The projection

[`packages/capability/src/to-toolkit.ts`](https://github.com/joelhooks/rat-stack/blob/main/packages/capability/src/to-toolkit.ts) turns contracts into Effect tools. It projects input, output, failure, and annotations.

[`apps/site/src/app.ts`](https://github.com/joelhooks/rat-stack/blob/main/apps/site/src/app.ts):

- Supplies the toolkit to `McpServer.toolkit`.
- Serves it at [/mcp](/mcp).
- Serves public documents as resources.
- Serves skills as prompts.

## The application tool is the same job

[`apps/site/src/capabilities/index.ts`](https://github.com/joelhooks/rat-stack/blob/main/apps/site/src/capabilities/index.ts) includes `joinInterest` in the hosted toolkit. Its [contract](https://github.com/joelhooks/rat-stack/blob/main/packages/core/src/join-interest-contract.ts) requires contact consent, a page ticket, and the approved card. The same requirements apply over MCP.

The HTTP alternative is `POST /api/joinInterest`. The [first observed application](/lore/two-lines-of-curl-is-a-front-door) uses that route without fetching MCP. The job does not need a protocol-specific handler.

Use [code mode](/lore/one-program-can-replace-several-tool-calls) to combine content calls. It does not expose `joinInterest` inside the sandbox.

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

## Sources

1. [MCP tools specification](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)
   Primary source. MCP tools specification Accessed 2026-10-02.

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

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

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

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

## Linked from

- add-a-capability → Learn how one contract and its handler become a command, HTTP route, MCP tool, browser RPC, and sandbox call. → [Read page](https://ratstack.sh/skills/add-a-capability)

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

- An agent applied through Markdown and HTTP → One observed application used the Markdown page and llms.txt, then one POST; confirmation followed 88 seconds later. → [Read page](https://ratstack.sh/lore/two-lines-of-curl-is-a-front-door)

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

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

- Dependency vendoring rules (vendor/README.md) → How to pin an unpublished package and when to remove the local copy. → [Read page](https://ratstack.sh/vendor/README.md)

- Devtools → Development-only capabilities inspect calls and lifecycle transitions without entering production bundles. → [Read page](https://ratstack.sh/systems/devtools)

- Effect + Alchemy peers → Public repositories that share rat-stack's prerelease lines. → [Read page](https://ratstack.sh/resources/peers)

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

- HATEOAS → Links in a representation tell its reader what to do next; rat-stack applies that idea to agent-facing pages and responses. → [Read page](https://ratstack.sh/lore/hateoas)

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

- Interest signup → Agent-only applications start email confirmation through interfaces owned by core and delivery implemented in a separate package. → [Read page](https://ratstack.sh/systems/interest)

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

- Learn mode presents concepts at useful depths → An agent presents source-derived concepts during real work and keeps learning events in a private local log. → [Read page](https://ratstack.sh/systems/learn)

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

- Lint and type escape ledger (debt.md) → A source-linked count of repo-owned lint and type escapes. → [Read page](https://ratstack.sh/debt.md)

- 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 program can replace several tool calls → Code mode combines typed content calls inside one bounded execute request. → [Read page](https://ratstack.sh/lore/one-program-can-replace-several-tool-calls)

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

- 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 King carries signed mail between named agents → Rat King gives agents named mailboxes, signed messages, optional encryption, and Pi, CLI, and MCP clients. → [Read page](https://ratstack.sh/lore/rat-king)

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

- uncomplect → Find responsibilities that a rat-stack design combines, separate them into capabilities, cartridges, machines, features, and clients, and enforce that separation through types and checks. Use when asked to simplify, review, or replace a design, "what would Rich Hickey do", "optimize for deletion", or "define this error out of existence". → [Read page](https://ratstack.sh/skills/uncomplect)

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

- Workshop setup help → An attendee's agent reports where Tokenmaxx setup is stuck, gets known fixes for that step, and later reads the desk's answer. → [Read page](https://ratstack.sh/systems/workshop-help)

## Unlinked mentions

- [Agent rules for rat-stack (AGENTS.md)](https://ratstack.sh/AGENTS.md) → Its Api is the contract, and Domain’s own HTTP, MCP, and CLI projections are its surfaces.

- [An MCP your users want](https://ratstack.sh/lore/an-mcp-your-users-want) → The hosted site’s MCP includes execute because demonstrating the sandbox is the site’s job.¶

- [Build and run rat-stack (README.md)](https://ratstack.sh/README.md) → ts and the MCP and catalog cases in apps/cli/test/cli.e2e.test.ts

- [Capabilities](https://ratstack.sh/systems/capabilities) → MCP returns it as a tool error.¶

- [HATEOAS](https://ratstack.sh/lore/hateoas) → Next-action links in capability and MCP responses remain a goal.

- [Hosted agent interfaces](https://ratstack.sh/systems/agent-front-door) → The MCP execute tool runs the same job.¶

- [Interest signup](https://ratstack.sh/systems/interest) → MCP request tracing is disabled in the protocol implementation for modern and legacy protocols.

- [keep-or-cut](https://ratstack.sh/skills/keep-or-cut) → catalog, OpenAPI, MCP, and code-mode cases from apps/cli/test/cli.e2e.test.ts¶

- [learn](https://ratstack.sh/skills/learn) → They use the same local store as stdio MCP.

- [Learn mode presents concepts at useful depths](https://ratstack.sh/systems/learn) → Public HTTP and MCP calls operate on supplied progress.

- [Lint and type escape ledger (debt.md)](https://ratstack.sh/debt.md) → Reason: HttpRouter declares asHttpEffect’s error as unknown upstream; the MCP transport answers every request itself, so a failure here is a defect.

- [One program can replace several tool calls](https://ratstack.sh/lore/one-program-can-replace-several-tool-calls) → The MCP execute tool.¶

- [One schema, three surfaces](https://ratstack.sh/lore/one-schema-three-surfaces) → CLI and MCP do not consume the generated OpenAPI JSON.¶

- [Purpose and boundaries of rat-stack (VISION.md)](https://ratstack.sh/VISION.md) → Coming: extract the existing agent front door in apps/site (REST, MCP, A2A, code-mode sandbox, rate limits) into a cartridge that a project provides instead of inherits.

- [Schema projections: 2026-09-18 history](https://ratstack.sh/resources/schema-projections-and-code-mode) → MCP: Module: unstable/ai Entry: Tool.make(name, { parameters, success, failure, dependencies, needsApproval }), Toolkit.make(...), McpServer.toolkit(toolkit), McpServer.layerStdio / layerHttp Schema goes in as: parameters, success, failure

- [Workshop setup help](https://ratstack.sh/systems/workshop-help) → ts files, answers, and reads one report over MCP, HTTP, and RPC.¶
