# Hosted agent interfaces

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

## What it does

`apps/site` hosts the public documentation and agent interfaces.
A capability is one named action with shared input, output, and failure definitions and a server-side implementation.

- MCP means Model Context Protocol. It lets an agent discover and call tools.
- A2A means Agent2Agent protocol. This site uses it to answer documentation questions through search and read.
- Discovery cards describe how to connect with each protocol.
- [OpenAPI](/openapi.json) describes the HTTP API for the registered capabilities, including inputs, outputs, and errors.
- The [agent guide](/llms.txt) explains connection, search, read, and following links between documentation pages.
- The hosted registry includes search, graph traversal, flags, prompts, CAFE news and profiles, learning, code mode, and `joinInterest`.
- [Live OpenAPI](/openapi.json) lists the current HTTP operations. Optional feedback operations depend on the auth configuration.

### Run a program instead of several calls

Use `POST /api/execute` with a JSON `code` string. The MCP `execute` tool runs the same job.

[Code mode](/lore/one-program-can-replace-several-tool-calls) runs several capability calls in one program inside a restricted environment.
`joinInterest` cannot run there.

Source: callable definitions 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).

```js
const found = await tools.search({ query: "cartridges", limit: 1 });
const page = await tools.read({ id: found.matches[0].id });
return { title: page.title, id: page.id };
```

The program passes the search result directly to read.

MCP supports protocol versions 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, and 2024-11-05. The newest is stateless. Older clients initialize sessions backed by a Durable Object, Cloudflare's feature for persistent state and compute.

A2A answers documentation questions through search and read. RPC means remote procedure call: a client calls a named operation on the server. Browser RPC serves the browser separately.

## The standard

- Application calls use shared capability value definitions and server-side implementations.
- Discovery and static pages handle routing. Domain calls stay in capability handlers.
- Public API access needs no account or access token.
- [Interest signup](/systems/interest) has its own consent and email-confirmation rules.
- `execute` runs an async function body in a fresh Dynamic Worker, a Cloudflare Worker loaded at runtime.
- It sets `globalOutbound: null` to block outbound network access.
- Imports, exports, and `fetch` are unavailable.
- The program can call only declared capabilities.
- API and MCP allow 120 requests per IP per 60 seconds.
- Execute also allows 6 per IP and 300 total per 60 seconds.
- Native Cloudflare counters apply separately per location.

These routes exist today. A reusable cartridge for agent interfaces remains planned.
A cartridge is a package for one job, with its implementation and required infrastructure.

## Content asset cache

`ContentStore` shares completed catalogs, search indexes, learning decks, and graph views within one Worker isolate.
Concurrent cold requests each perform their own asset reads.
The cache stores a value only after its read and validation succeed.
Failed or interrupted reads leave the cache empty.

Pending reads must not use a shared promise, fiber, latch, or response body.
Those values can belong to the first request's runtime context.
Warm requests reuse decoded data without new asset I/O.

`test/cold-content-runtime.test.ts` sends concurrent first requests through a fresh local Worker.
Its asset adapter adds a delay to make cold reads overlap.
The test uses workerd, production content routes, and the reader wrapper.

## How to check

1. Read the [MCP connection card](/.well-known/mcp.json).
2. Read the [A2A card](/.well-known/agent-card.json).
3. Read [OpenAPI](/openapi.json).
4. Compare the descriptions with `apps/site/src/capabilities/index.ts`.
5. Use the `tools/list` request in [llms.txt](/llms.txt).
6. Search for a public document.
7. Read the document.
8. Run `pnpm --filter @rat-stack/site test` for protocol routing, rate limiting, and sandbox behavior.
9. Confirm the live cards and capability list before advertising a new agent path.
10. Run `pnpm --filter @rat-stack/site exec vitest run test/cold-content-runtime.test.ts` to check cold-request isolation.

Check a new deploy live as well as running local tests.

## Sources

1. [Hosted application routes](https://github.com/joelhooks/rat-stack/blob/main/apps/site/src/app.ts)
   GitHub joelhooks/rat-stack. Discovery, content negotiation, and protocol routing. Accessed 2026-10-01.

2. [Agent discovery content](https://github.com/joelhooks/rat-stack/blob/main/apps/site/src/content.ts)
   GitHub joelhooks/rat-stack. MCP versions, connection examples, and discovery cards. Accessed 2026-10-01.

3. [Hosted capability registry](https://github.com/joelhooks/rat-stack/blob/main/apps/site/src/capabilities/index.ts)
   GitHub joelhooks/rat-stack. The hosted content and execute capability list. Accessed 2026-10-01.

4. [Code-mode Worker loader](https://github.com/joelhooks/rat-stack/blob/main/apps/site/src/sandbox-worker-loader.ts)
   GitHub joelhooks/rat-stack. Isolated execution and outbound network limits. Accessed 2026-10-01.

5. [Native rate limits](https://github.com/joelhooks/rat-stack/blob/main/apps/site/src/rate-limits.ts)
   GitHub joelhooks/rat-stack. Request counters and per-stage namespaces. Accessed 2026-10-01.

## Lore on this page

- [MCP is another surface](/lore/mcp-is-another-surface)
- [CAFE names the Cloudflare, Alchemy, Foldkit and Effect stack](/lore/cafe-stack)
- [One program can replace several tool calls](/lore/one-program-can-replace-several-tool-calls)
- [Workers answer requests; Durable Objects own named state](/lore/workers-answer-requests-durable-objects-own-named-state)
- [A cartridge owns one job and its resources](/lore/cartridges)

## Linked from

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

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

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

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

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

## Unlinked mentions

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