If you build web apps with Next.js and follow the wave of autonomous AI agents, you've likely hit an awkward architectural dilemma.
You already have a working Next.js App Router project: dozens of route handlers live in app/api, auth is wired up, your database is connected, and Zod validates incoming payloads. Then a new business request lands: "Let's hook up an agent powered by Claude or a local LLM over Model Context Protocol (MCP) so it can create orders, generate invoices, or check warehouse stock on its own."
How do teams usually handle this? Someone sits down and starts duplicating code: spinning up a separate MCP server repo, copying parameter schemas by hand, and either duplicating database calls or proxying HTTP requests. Before long, you have two parallel codebases that drift out of sync the moment anyone changes a method signature.
That headache disappears with the open-source library Vovk.ts (source code on GitHub).
The Unified Procedure Principle: One Endpoint for Web and AI
Vovk.ts rests on a remarkably clean architectural idea: the Unified Procedure. You write your method's business logic once right inside your Next.js structure, and the library projects it into three independent targets on the fly:
- A standard Next.js Route Handler HTTP endpoint.
- A strictly typed RPC client for frontend components without a separate codegen step (similar to tRPC).
- A Model Context Protocol (MCP) Tool complete with a ready-made JSON argument schema for AI agents!
Here is what that looks like in real code:
// app/api/controllers/OrdersController.ts
import { prefix, get, post } from 'vovk';
import { z } from 'zod';
const CreateOrderSchema = z.object({
customerId: z.string().describe('Unique customer ID'),
itemsCount: z.number().int().positive().describe('Number of items in the order'),
totalAmount: z.number().describe('Total order amount in rubles'),
});
@prefix('orders')
export class OrdersController {
@post('create')
async createOrder({ body }: { body: z.infer<typeof CreateOrderSchema> }) {
// Your regular database business logic
const order = await db.orders.create({ data: body });
return { success: true, orderId: order.id };
}
}
Now for the magic: to expose this endpoint to an AI assistant in Claude Desktop or Cursor, you simply wire up the generated MCP handler:
// app/api/mcp/route.ts
import { createMcpHandler } from 'vovk/mcp';
import { OrdersController } from '../controllers/OrdersController';
// Automatic export of MCP tools with Zod schemas
export const { GET, POST } = createMcpHandler({
controllers: [OrdersController],
serverInfo: {
name: 'store-management-mcp',
version: '1.0.0',
},
});
Why This Changes AI Agent Development
You no longer have to maintain a zoo of glue microservices:
- Zero type drift: change a field in your Zod schema, and TypeScript flags frontend mismatches immediately while the agent receives the updated argument spec without restarts or manual manifest edits.
- Unified auth: all your existing Next.js sessions, cookies, and JWT tokens keep working out of the box.
- Documentation ecosystem: alongside MCP, Vovk.ts also exports clean OpenAPI 3.1 specs. If you need standalone documentation portals built from OpenAPI and MCP specs, check out our review of Sourcey: a static documentation portal generator.
Vovk.ts turns an existing Next.js monolith or API into a full-fledged AI tool gateway in roughly 15 minutes.
