Expose Your App to AI Agents in 30 Minutes: A MCP Integration Pattern

The Problem Nobody Talks About

You've built a solid application. Now an AI agent (Claude, Cursor, or any MCP-compatible assistant) wants to use it.

What do you do?

Most developers end up writing:

• A custom MCP server
• JSON-RPC handlers
• Schema definitions
• CLI wrappers
• OpenAI tool definitions

That's three separate integrations for the same capability — each with its own quirks, validation logic, and maintenance burden.

Sound familiar? That's exactly the problem Ageniti was built to solve.

The Core Idea: Define Once, Expose Everywhere

With Ageniti, you define a typed action once, and it automatically generates:

• An MCP tool server
• A CLI with flags and JSON output
• OpenAI-compatible tool schema
• Vercel AI SDK tool definitions

All from one contract. One source of truth.

Let's Build Something Real

Let's say you have a function that searches your product database. Here's how you'd expose it to everything.

Step 1: Define the Action

import { action, runtime } from '@ageniti/core';

// Define your action with typed inputs and outputs
const searchProducts = action({
  id: 'search-products',
  description: 'Search product catalog by keyword',
  input: z.object({
    query: z.string().describe('Search query'),
    limit: z.number().optional().default(10),
  }),
  handler: async ({ query, limit }) => {
    // Your existing business logic
    return await productService.search({ query, limit });
  },
});

Step 2: Generate Surfaces

// MCP Server (for Claude, Cursor, etc.)
import { createMCPServer } from '@ageniti/mcp';
const server = createMCPServer([searchProducts]);
// Run with: node server.js

// CLI (for terminal workflows)
import { createCLI } from '@ageniti/cli';
const cli = createCLI([searchProducts]);
// Run with: ageniti search-products --query "shoes"

// OpenAI Tools (for AI SDK integrations)
import { toOpenAITools } from '@ageniti/openai';
const tools = toOpenAITools([searchProducts]);
// Use with: OpenAI.chat.completions.create({ tools })

Same action. Three surfaces. Zero duplication.

Why This Matters

Here's what you'd normally need to maintain:

Concern	Hand-written	With Ageniti
Input validation	Custom per-surface	Shared, typed
Error handling	Duplicated	One place
Schema sync	Manual	Automatic
CLI parsing	Custom flags	Generated
MCP protocol	Custom server	Drop-in

Every new capability you add only needs one definition instead of three separate implementations.

The Runtime Layer

Behind the scenes, every action runs through a shared runtime that handles:

• Validation — Zod schemas, always enforced
• Authorization — Run hooks before execution
• Timeouts & Retries — Configurable per-action
• Structured Output — Consistent response shapes
• Logging — Built-in action execution logs

const searchProducts = action({
  // ... definition
  runtime: {
    timeout: 5000,
    retries: 2,
    hooks: {
      before: async (ctx) => {
        if (!ctx.user.canSearch) {
          throw new UnauthorizedError();
        }
      },
    },
  },
});

What's Actually Different

Ageniti isn't another AI framework or orchestration layer. It doesn't plan, reason, or replace your app.

It's specifically the integration layer — the plumbing between your product and the agents that need to call it.

Think of it like:

• prisma for your database schema → you're writing actions
• react-query for your API state → you're using the runtime
• zod for your validation → you're getting type safety

You keep your app architecture exactly as-is. You just add a thin wrapper to expose it safely.

Getting Started

npm install @ageniti/core

Then check out the Getting Started guide for a complete walkthrough.

The bootstrap file also works directly with coding agents — feed BOOTSTRAP.md to Cursor or Claude Code and it will clone, set up, and walk through your first action.

The Real Win

The goal isn't to use Ageniti. The goal is to have your application actually work with the AI ecosystem without spending weeks on integration boilerplate.

Every action you define is infrastructure that pays off every time you add a new surface — MCP, CLI, OpenAI tools, whatever comes next.

If you've been building around AI agents and feeling the pain of integration sprawl, I'd love to hear what's blocking you.