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

Free workshop: [how to burn a trillion tokens and get good results](/tokenmaxx#interested).

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 invocation.
- Input JSON Schema.
- Optional output JSON Schema.

A client that speaks MCP can discover names and arguments without learning a separate invocation format. In rat-stack, MCP is a [surface](/lore/one-schema-three-surfaces), not a second implementation of the job.

## 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/mischief/src/app.ts`](https://github.com/joelhooks/rat-stack/blob/main/apps/mischief/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/mischief/src/capabilities/index.ts`](https://github.com/joelhooks/rat-stack/blob/main/apps/mischief/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. MCP does not remove that boundary.

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/mischief/src/app.ts](https://github.com/joelhooks/rat-stack/blob/main/apps/mischief/src/app.ts)
   GitHub. apps/mischief/src/app.ts Accessed 2026-10-02.

4. [apps/mischief/src/capabilities/index.ts](https://github.com/joelhooks/rat-stack/blob/main/apps/mischief/src/capabilities/index.ts)
   GitHub. apps/mischief/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 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 → Domain behaviors on generated surfaces share one schema-typed contract and one handler. → [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 + Alchemy peers → Public repositories that share rat-stack's prerelease lines. → [Read page](https://ratstack.sh/resources/peers.svx)

- 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 surfaces. → [Read page](https://ratstack.sh/lore/hateoas)

- Hosted agent front door → 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; delivery stays behind job-shaped ports outside core. → [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-rat-stack → See how Effect, XState, TypeScript, Alchemy, and four agent interfaces fit together. → [Read page](https://ratstack.sh/skills/learn-rat-stack)

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

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

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

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

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

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

- Two lines of curl is a front door → 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)

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

## Unlinked mentions

- [AGENTS.md](https://ratstack.sh/AGENTS.md) → ts, so MCP is a prerequisite for code mode.

- [Capabilities](https://ratstack.sh/systems/capabilities) → The MCP tools/list request in the agent guide returns the same seven names.¶

- [HATEOAS](https://ratstack.sh/lore/hateoas) → Direction: next-action links in capability and MCP responses; projecting a capability does not by itself supply those links.¶

- [Hosted agent front door](https://ratstack.sh/systems/agent-front-door) → MCP supports protocol versions 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, and 2024-11-05.

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

- [learn-rat-stack](https://ratstack.sh/skills/learn-rat-stack) → packages/capability/src projects the shared contract and implementation into commands, HTTP routes, MCP tools, sandbox calls, and browser RPC.¶

- [One program can replace several tool calls](https://ratstack.sh/lore/one-program-can-replace-several-tool-calls) → joinInterest belongs to the outer API/MCP registry.

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

- [rat-stack](https://ratstack.sh/) → The hosted REST, MCP, A2A, and sandbox routes already run; extracting their generic front door into its own cartridge is coming.

- [Schema projections: 2026-09-18 history](https://ratstack.sh/resources/schema-projections-and-code-mode.svx) → Integration layer, not a tool author: ingests MCP servers, OpenAPI, GraphQL, Google Discovery into one catalog, adds auth and per-tool policy (allow / approve / block), serves the catalog back over MCP.

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