AgentBack documentation

A TypeScript dependency-injection framework with HTTP (REST) and MCP servers that plug into the same container and validate against the same Zod schemas. This is the place to learn the ideas and build with them.

New here? Read the root README for the one-page tour and the 30-second code feel, then come back for the depth.

How the framework thinks

Three ideas carry the whole framework. Everything in these docs is an elaboration of one of them:

1. Everything is a binding in a context. The Application is a DI Context. Controllers, MCP tool classes, services, config, and even the servers themselves are just bindings the framework discovers by tag. New capability = new binding; you never edit a central registry.
2. Schemas live once, on the decorator. A route's or tool's Zod schema is simultaneously the runtime validator, the z.infer TypeScript type, the OpenAPI/MCP contract, and the rendered docs. One artifact, many views.
3. Servers are components. REST and MCP are interchangeable, composable plug-ins over the same container — run either, or both from one process.

If you internalize those three, the API surface mostly writes itself.

Learning path

Read top-to-bottom the first time; jump around afterwards.

Blog — design notes and release stories

Concepts — understand the machine

Guides — build something

Reference & design

Every package under packages/ carries its own README.md with its exports, a usage snippet, and where it sits in the layering.

Server extensions (install* onto a running REST server): health/readiness probes · Prometheus metrics · rate limiting (in-memory or Redis, 429 + RateLimit-* headers).

Metering & payments (subclass the dispatcher / mount a rail): usage metering (per-principal UsageEvents → audit-log sinks + quota) · payments (x402 / MPP / Stripe) — see the architecture doc.

The shortest possible example

import {z} from 'zod';
import {api, get} from '@agentback/openapi';
import {RestApplication} from '@agentback/rest';

@api({basePath: '/greet'})
class GreetingController {
  @get('/hello/{name}', {
    path: z.object({name: z.string().min(1)}),
    response: z.object({greeting: z.string()}),
  })
  async hello(input: {path: {name: string}}) {
    return {greeting: `Hello, ${input.path.name}!`};
  }
}

const app = new RestApplication();
app.restController(GreetingController);
await app.start();
// GET /greet/hello/world  -> {"greeting":"Hello, world!"}
// GET /openapi.json       -> OpenAPI 3.1.1 derived from the Zod schemas

Change GreetingController to an @mcpServer() with @tool(...) methods and the same schemas become an MCP tool surface instead — see Build an MCP server.

Runnable examples

Each guide maps to a working example you can run:

pnpm install && pnpm build       # build first — tests/examples run against dist/
pnpm -F hello-rest start         # REST + Swagger UI + Context Explorer
pnpm -F hello-mcp test           # MCP over stdio, driven by a test client
pnpm -F hello-hybrid start       # REST + MCP from one process, both UIs
pnpm -F hello-client start       # the typed client calling hello-rest's schemas

Conventions in these docs

• Code blocks are real, compiling TypeScript drawn from the packages and examples — not pseudocode.
• ESM only: relative imports carry .js extensions in actual source; doc snippets omit them for readability where the import is from a package.
• "Slot 0 / slot 1+" refers to a handler method's parameter positions — see Schema-first decorators.