Vovk.ts: How to Turn Next.js Endpoints into AI Agent ToolsNote · digest for October 27
Isometric 3D architectural model of Vovk.ts projecting a single Next.js controller into an HTTP endpoint, RPC client, and MCP tool.
Note2 sections≈ 4 min

Vovk.ts: How to Turn Next.js Endpoints into AI Agent Tools

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:

  1. A standard Next.js Route Handler HTTP endpoint.
  2. A strictly typed RPC client for frontend components without a separate codegen step (similar to tRPC).
  3. 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.

Want a deep diveVotes help us choose what to break down in detail. This material has 0 votes.
Sources · 3