Skip to main content
Anvil is a Node.js backend framework designed for developers building AI-powered and agent-driven applications. It gives you the ergonomics of Express, the structural clarity of Next.js-style file-based routing, and a native agentic layer — MCP auto-exposure, a tool registry, agent orchestration, distributed tracing, durable checkpointing, and more — without requiring a second codebase, a separate config file, or a pile of duplicated schemas.

​
The problem Anvil solves

Building a backend for an AI-first product today forces you to maintain parallel worlds: one codebase for your HTTP API, another set of schemas for your MCP tools, manual wiring for tracing and cost observability, and no standard way to resume an agent run after a crash. The result is duplicated logic, schema drift, and brittle glue code that breaks every time a model or SDK changes. Anvil collapses all of that into a single framework:
  • No duplicate MCP schemas — mark any route mcp: { expose: true } and it becomes an MCP tool automatically. The same handler, the same Zod schema, zero extra code.
  • No manual tracing wiring — every request, model call, tool invocation, and token cost is captured in the built-in trace store and surfaced through the /_anvil dashboard.
  • No crash-resume glue — durable checkpointing lets agent runs survive restarts; human-in-the-loop gates pause execution until approval arrives.
  • No framework-per-concern — routing, middleware, CORS, static files, MCP, agent orchestration, evals, and RAG are all first-class citizens in the same package.

​
Key features

File-Based Routing

Drop a get.ts in server/routes/users/ and you have GET /users. No config, no decorators, no registration step.

Dynamic Routes

Use [param] folders for path parameters and [...param] for catch-all segments. Validate them with Zod at compile time.

Scoped Middleware

Place _middleware.ts next to your routes for folder-scoped middleware. Compose multiple middleware functions with the built-in compose() helper.

Context API

A single Context object replaces Express’s (req, res) pair — typed params, cached body parsing, and first-class response helpers.

MCP Auto-Exposure

Any route annotated with meta.mcp.expose is instantly available as an MCP tool. Run anvil mcp to serve tools over Streamable HTTP or --stdio for Claude Desktop.

Agent Routes

An agent.ts file is a streaming agent endpoint. It runs the full model↔tool loop, validates inputs, tracks cost, and aborts cleanly on client disconnect.

​
Requirements

  • Node.js ≥ 20 (uses the native Request/Response Web API built into Node 20+)
  • ESM project — your package.json must include "type": "module"
  • npm, yarn, or pnpm

​
CLI overview

Anvil ships with a CLI that handles the full development and deployment lifecycle:
CommandDescription
anvil devDev server with watch mode — TypeScript routes are loaded on the fly
anvil buildGenerates .gen/routes.ts and bundles dist/server.mjs
anvil startRuns the production bundle
anvil lintValidates routes: checks param schema keys, MCP JSON Schema compatibility
anvil mcpServes MCP-exposed routes and server/tools/ over Streamable HTTP
anvil eval <file>Runs an eval suite against an agent; exits non-zero on failure
anvil replay <traceId>Re-runs a captured trace with mocked responses

​
Example apps

Three complete, runnable projects live in the GitHub repo:

basic-api

Express-parity REST API: dynamic routes, scoped middleware, static files, and a route exposed as an MCP tool.

mcp-server

A minimal project demonstrating the zero-extra-code MCP wedge — CRUD routes and a standalone tool, all served by anvil mcp.

agent-hitl

An agent route with a refund tool gated behind human approval — suspend, approve, and resume, with durable checkpointing.

​
Next steps

Ready to build? Start with the quickstart to have a working Anvil API in under five minutes.

Quickstart

Install Anvil, create your first route, and run the dev server.

Installation

Detailed setup: Node version, package managers, ESM config, and optional peer deps.