Framework Comparison
Capstan sits at the intersection of full-stack web development and AI agent operability. This page compares it with Next.js, Mastra, and LangGraph to help you decide which framework fits your use case.
Capstan vs Next.js
| Feature | Capstan | Next.js |
|---|---|---|
| Primary audience | Human users + AI agents | Human users |
| API definition | defineAPI() with Zod schemas | Route handlers or API routes |
| Multi-protocol | HTTP + MCP + A2A + OpenAPI from one definition | HTTP only (manual OpenAPI) |
| Agent manifest | Auto-generated at /.well-known/capstan.json | Not available |
| MCP server | Built-in (capstan mcp) | Requires separate implementation |
| A2A protocol | Built-in | Not available |
| OpenAPI spec | Auto-generated from Zod schemas | Requires third-party tools |
| Server runtime | Hono (lightweight, Web Standards) | Custom (Turbopack/Webpack) |
| Database | Drizzle ORM with defineModel() | BYO (Prisma, Drizzle, etc.) |
| Auth | Built-in JWT + API key for agents | NextAuth.js (community package) |
| Policy engine | definePolicy() with allow/deny/approve/redact | Not available |
| Approval workflow | Built-in human-in-the-loop | Not available |
| Verification | capstan verify (AI TDD loop) | tsc + linting |
| SSR | React SSR with loaders | React Server Components |
| ISR | Built-in renderMode: "isr" | Built-in (page-level revalidate) |
| RAG / vector search | Built-in field.vector(), defineEmbedding() | Not available |
| Rate limiting | Built-in per auth type | Requires middleware / third-party |
| Ecosystem maturity | Early stage | Mature, large ecosystem |
Capstan vs Mastra
Mastra is a TypeScript framework for building AI agents and workflows.
| Feature | Capstan | Mastra |
|---|---|---|
| Focus | Full-stack apps consumed by agents + humans | AI agent orchestration and workflows |
| Approach | "App that agents can use" | "Agent that uses apps" |
| API layer | defineAPI() with automatic multi-protocol | Agent tools with function calling |
| Web UI | File-based routing, React SSR | Optional playground UI |
| Auth | JWT sessions + API keys | BYO authentication |
| Policy engine | Built-in with approval workflow | Not available |
| LLM integration | Framework-agnostic (agents call your APIs) | Built-in LLM orchestration |
Capstan vs LangGraph
LangGraph is a framework for building stateful, multi-actor AI applications using graph-based workflows.
| Feature | Capstan | LangGraph |
|---|---|---|
| Language | TypeScript | Python (primary), TypeScript |
| Focus | Full-stack apps with agent interfaces | Stateful agent workflow graphs |
| Architecture | Request/response API framework | Graph-based state machines |
| Web UI | Built-in file-based routing + React SSR | LangGraph Studio (separate tool) |
| Human-in-the-loop | Policy-based approval workflow | Graph interrupt nodes |
| Multi-agent | Agents call your APIs independently | Multi-actor graphs with shared state |
Feature Comparison Table
+ Built-in ~ Partial / Plugin - Not available
| Feature | Capstan | Next.js | Mastra | LangGraph |
|---|---|---|---|---|
| HTTP API framework | + | + | - | - |
| MCP server (auto-generated) | + | - | - | - |
| A2A protocol | + | - | - | - |
| OpenAPI auto-generation | + | - | - | - |
| File-based routing | + | + | - | - |
| React SSR | + | + | - | - |
| ISR (stale-while-revalidate) | + | + | - | - |
| Built-in database layer | + | - | ~ | - |
| Built-in auth (JWT + API key) | + | - | - | - |
| Policy engine | + | - | - | - |
| Approval workflow | + | - | - | ~ |
| RAG / vector search | + | - | + | ~ |
| Rate limiting (per auth type) | + | - | - | - |
| Workload identity (SPIFFE) | + | - | - | - |
| LLM orchestration | - | - | + | + |
| Multi-agent workflows | - | - | + | + |
| Graph-based state machines | - | - | - | + |
| TypeScript-first | + | + | + | ~ |
| Production maturity | beta | mature | early | early |
Key Differentiators
Shared Contract
One defineAPI() call produces four surfaces: an HTTP endpoint, an MCP tool, an A2A skill, and an OpenAPI operation. The Zod schema is the single source of truth. You never write glue code to keep them in sync.
Agent-Native
Agent support is not an afterthought or a plugin. Every route is automatically discoverable via MCP and A2A. The /.well-known/capstan.json manifest tells agents exactly what your app can do, what inputs are required, and what policies govern access.
Policy-First
Policies are declarative rules evaluated before handlers, with built-in support for approval workflows. An agent requesting a destructive action can be paused until a human approves.
Verification Loop
capstan verify runs a multi-step cascade that catches issues across types, routes, schemas, policies, agent manifests, OpenAPI specs, and runtime health. When paired with AI code generation, it forms a "generate, verify, repair" loop.
When to Use Capstan
- You are building an application that AI agents will interact with programmatically
- You want a single
defineAPI()call to generate HTTP, MCP, A2A, and OpenAPI endpoints - You need human-in-the-loop approval workflows for agent actions
- You want built-in agent authentication (API keys) alongside human auth (JWT)
- You prefer full-stack TypeScript with a lightweight Hono-based server
When NOT to Use Capstan
- You are building a primarily human-facing web application with no agent requirements
- You need React Server Components or the Next.js app router
- You rely on a mature ecosystem with extensive third-party plugins
- Your team is Python-only and does not want to adopt TypeScript
- You are building complex multi-step agent workflows with LLM orchestration (consider Mastra or LangGraph)
Summary
Choose Capstan when you are building a full-stack application -- with web pages, a database, authentication -- that should also be natively accessible to AI agents via MCP, A2A, and OpenAPI, all generated from a single defineAPI() call.
Choose Next.js when you are building a primarily human-facing web application and need the mature React ecosystem and Vercel integration.
Choose Mastra when you are building AI agents that orchestrate LLM calls and workflows -- your agent is the primary actor, not a consumer of your app.
Choose LangGraph when you are building complex, stateful multi-agent systems with graph-based workflow logic and persistent state checkpointing.