Turn Any REST API into MCP Tools in 5 Minutes

Your REST API has 200 endpoints. Your AI agent can call exactly zero of them.

That is the gap MCP was built to close. The Model Context Protocol gives AI models a universal interface for calling external tools — like USB-C for software. But turning your API into MCP tools means writing a tool definition for every single endpoint: input schemas, output parsing, error handling, authentication, and description text that an LLM can actually understand.

For a 50-endpoint API, that is 1,500+ lines of hand-written boilerplate. For a 200-endpoint API, it is a full-time job.

@taskade/mcp-openapi-codegen eliminates that job entirely. Point it at any OpenAPI 3.0 spec — a URL or a local file — and it generates the complete set of type-safe MCP tools in seconds. One command. Zero hand-written definitions. The generated TypeScript is human-readable, Prettier-formatted, and ready to commit.

This is how Taskade auto-generates 50+ MCP tools from a single spec. Zero manual maintenance. When the API changes, the tools update automatically.

This guide walks through the full process — from installation to production deployment — and compares every major approach to OpenAPI-to-MCP conversion in 2026.

What Is MCP?

The Model Context Protocol is an open standard introduced by Anthropic in November 2024. It defines how AI models discover and call external tools through a structured JSON-RPC interface.

Think of it this way: before MCP, every AI integration was a custom adapter. Connecting Claude to your database meant writing one integration. Connecting it to your CRM meant writing another. Each tool had its own schema, its own error format, its own authentication flow. The result was a fragmented ecosystem where AI agents could not interoperate with each other's tools.

MCP fixes this with a single protocol:

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   MCP: THE UNIVERSAL TOOL PROTOCOL                          │
│                                                             │
│   ┌──────────┐     ┌──────────────┐     ┌───────────────┐   │
│   │  Claude   │────▶│  MCP Server  │────▶│  Your API     │   │
│   │  Cursor   │◀────│  (Tools)     │◀────│  (REST/gRPC)  │   │
│   │  Windsurf │     └──────────────┘     └───────────────┘   │
│   │  VS Code  │                                             │
│   └──────────┘                                              │
│                                                             │
│   One protocol. Any client. Any server. Any tool.           │
│                                                             │
└─────────────────────────────────────────────────────────────┘

The adoption numbers speak for themselves:

• 97M+ MCP SDK downloads per month
• 10,000+ MCP servers in the ecosystem
• Backed by Anthropic, OpenAI, Google, Microsoft
• Supported in Claude Desktop, Cursor, Windsurf, VS Code, Continue.dev, n8n

MCP is not a proposal. It is the standard. And if your API does not have an MCP server, your API is invisible to the fastest-growing class of software users: AI agents.

The Problem: Manual MCP Tool Creation

Here is what a single hand-written MCP tool definition looks like:

server.tool(
  "createProject",
  "Create a new project in a workspace",
  {
    workspaceId: z.string().describe("The workspace ID"),
    name: z.string().describe("Project name"),
    description: z.string().optional().describe("Project description"),
    color: z.string().optional().describe("Color hex code"),
    templateId: z.string().optional().describe("Template ID to clone"),
  },
  async ({ workspaceId, name, description, color, templateId }) => {
    const response = await fetch(
      `https://api.example.com/workspaces/${workspaceId}/projects`,
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${API_KEY}`,
        },
        body: JSON.stringify({ name, description, color, templateId }),
      }
    );
    const data = await response.json();
    return { content: [{ type: "text", text: JSON.stringify(data) }] };
  }
);

That is 28 lines for a single endpoint. A typical SaaS API has 50-200 endpoints.

And the boilerplate is the easy part. The hard part is keeping tool descriptions accurate enough for an LLM to use correctly, handling every authentication flow, normalizing complex response types, and updating everything when your API spec changes.

This is a code generation problem. You already have the API specification. The tool definitions should be derived automatically.

A word of caution: auto-generating MCP tools from an OpenAPI spec is not the same as blindly exposing every endpoint. Jeremiah Lowin, creator of FastMCP, argues that the biggest MCP anti-pattern is "REST-brain" — mirroring CRUD operations instead of designing for agent outcomes. Agent performance degrades above approximately 50 tools, nested parameter schemas confuse models, and raw API responses waste tokens. The right approach is codegen combined with curation: generate the tool definitions automatically, then use allowlists and response normalizers to expose only the tools agents actually need, with flat arguments and concise responses.

The Solution: @taskade/mcp-openapi-codegen

┌───────────────────────────────────────────────────────────────┐
│                                                               │
│   THE CODEGEN PIPELINE                                        │
│                                                               │
│   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐  │
│   │ OpenAPI  │──▶│  Parse   │──▶│ Generate │──▶│  .ts     │  │
│   │ 3.0 Spec │   │ + Deref  │   │ Zod +    │   │  Output  │  │
│   │ (YAML/   │   │ + Flat   │   │ Tool     │   │ (commit- │  │
│   │  JSON)   │   │          │   │ Defs     │   │  table)  │  │
│   └──────────┘   └──────────┘   └──────────┘   └──────────┘  │
│                                                               │
│   Input:   Your existing API spec                             │
│   Output:  Type-safe MCP tools (TypeScript + Zod)             │
│   Time:    < 10 seconds                                       │
│                                                               │
└───────────────────────────────────────────────────────────────┘

@taskade/mcp-openapi-codegen reads your OpenAPI 3.0 specification, resolves $ref references, flattens nested schemas into self-contained $defs, and generates a complete TypeScript file with:

• Zod schemas for every input parameter (type-safe validation)
• Tool definitions with LLM-friendly descriptions derived from your spec
• Path parameter handling (e.g., /projects/{projectId})
• Query parameter handling with correct types and defaults
• Request body parsing for POST/PUT/PATCH operations
• Prettier formatting — the output is clean, readable, and ready to commit

The key difference from runtime proxies (which translate API calls on the fly) is that codegen produces actual source code you own. You can inspect every generated tool, customize descriptions, and version-control changes alongside your codebase.

Step-by-Step Tutorial

Step 1: Install

npm install @taskade/mcp-openapi-codegen
# or
yarn add @taskade/mcp-openapi-codegen

Step 2: Create Your Codegen Script

Create a file called generate-mcp-tools.ts:

import { generateMcpTools } from "@taskade/mcp-openapi-codegen";
import * as path from "path";

async function main() {
  await generateMcpTools({
    // Point to your OpenAPI spec (URL or local file)
    specPath: "https://api.example.com/openapi.yaml",
// Where to write the generated tools
outputPath: path.resolve(__dirname, "tools.generated.ts"),

main();


Step 3: Run the Generator

npx tsx generate-mcp-tools.ts

The generator reads your spec, resolves all references, and writes a complete tools.generated.ts file. Every endpoint in your spec becomes a type-safe MCP tool definition.

Step 4: Create Your MCP Server

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { registerTools } from "./tools.generated.js";

const server = new McpServer({
  name: "my-api-mcp-server",
  version: "1.0.0",
});
// Register all generated tools with a custom fetch function
registerTools(server, {
  baseUrl: "https://api.example.com",
  fetchFn: async (url, init) => {
    return fetch(url, {
      ...init,
      headers: {
        ...init?.headers,
        Authorization: Bearer ${process.env.API_KEY},
      },
    });
  },
});
// Start the server
const transport = new StdioServerTransport();
server.connect(transport);

Step 5: Connect to Claude Desktop

Add this to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["tsx", "/path/to/your/server.ts"],
      "env": {
        "API_KEY": "your-api-key-here"
      }
    }
  }
}

Step 6: Test It

Restart Claude Desktop. Open a new conversation and ask:

"List all my projects and create a new one called Q1 Planning."

Claude will discover your MCP tools, call the correct endpoints, parse the responses, and execute multi-step workflows — all without you writing a single tool definition by hand.

The same configuration works with Cursor, Windsurf, Continue.dev, and any other MCP-compatible client.

Advanced Features

Selective Tool Exposure (Allowlists)

A 200-endpoint API should not expose 200 tools to an LLM. Context window overflow causes tool confusion and degraded performance. Research shows that selective curation dramatically improves agent accuracy.

Filter endpoints with an allowlist:

await generateMcpTools({
  specPath: "https://api.example.com/openapi.yaml",
  outputPath: "./tools.generated.ts",
  // Only expose these operations
  allowOperations: [
    "listProjects",
    "createProject",
    "getProjectById",
    "listTasks",
    "createTask",
    "updateTask",
  ],
});

Or use a predicate function for dynamic filtering:

await generateMcpTools({
  specPath: "https://api.example.com/openapi.yaml",
  outputPath: "./tools.generated.ts",
  allowOperations: (operationId, method, path) => {
    // Exclude all DELETE operations
    if (method === "delete") return false;
    // Exclude admin-only endpoints
    if (path.startsWith("/admin")) return false;
    return true;
  },
});

Response Normalizers

This is the feature that makes @taskade/mcp-openapi-codegen unique. Response normalizers let you inject contextual information into API responses before the LLM sees them. This transforms raw JSON data into actionable intelligence.

registerTools(server, {
  baseUrl: "https://api.example.com",
  responseNormalizers: {
    listProjects: (data) => {
      // Add clickable URLs so Claude can link to real resources
      return data.items.map((project) => ({
        ...project,
        url: `https://app.example.com/projects/${project.id}`,
        hint: "You can open this project in the browser.",
      }));
    },
  },
});

Without normalizers, Claude returns: "Project ID: abc123". With normalizers, Claude returns: "Here's your project: [Q1 Planning](https://app.example.com/projects/abc123)". The difference is the gap between information and action.

Custom Authentication

Inject any auth strategy — API keys, OAuth2 tokens, session cookies, or custom headers:

registerTools(server, {
  baseUrl: "https://api.example.com",
  fetchFn: async (url, init) => {
    const token = await getOAuth2Token(); // Your auth logic
    return fetch(url, {
      ...init,
      headers: {
        ...init?.headers,
        Authorization: `Bearer ${token}`,
        "X-Custom-Header": "value",
      },
    });
  },
});

Monorepo Support

For large projects, split the codegen and server into separate packages. Taskade's own MCP repository uses this pattern:

packages/
├── openapi-codegen/    # The generator library (npm: @taskade/mcp-openapi-codegen)
├── taskade-mcp-tools/  # Generated tools for Taskade's API
└── mcp-server/         # The MCP server (npm: @taskade/mcp-server)

Each package has a clear responsibility. When the API spec changes, you re-run codegen in taskade-mcp-tools/ and the server package picks up the new tools automatically.

Real-World: How Taskade Uses This in Production

Taskade does not just publish @taskade/mcp-openapi-codegen. We use it every day to power our own MCP server — @taskade/mcp-server — which exposes 50+ tools to Claude, Cursor, and every MCP-compatible client.

Here is the actual pipeline:

┌───────────────────────────────────────────────────────────────┐
│                                                               │
│   TASKADE MCP PIPELINE (PRODUCTION)                           │
│                                                               │
│   1. Fetch latest spec                                        │
│      $ yarn fetch:openapi                                     │
│      → Downloads taskade.com/api/documentation/yaml            │
│                                                               │
│   2. Generate tools                                           │
│      $ yarn generate:taskade-mcp-tools                        │
│      → Parses spec → allowlist filter → codegen               │
│      → Output: tools.generated.ts (50+ tools)                 │
│                                                               │
│   3. Commit + publish                                         │
│      → tools.generated.ts → @taskade/mcp-server on npm        │
│      → Users install: npx @taskade/mcp-server                 │
│                                                               │
│   API changes? Re-run steps 1-3. Zero manual updates.         │
│                                                               │
└───────────────────────────────────────────────────────────────┘

What the 50+ tools cover:

Response normalizers in action: When Claude lists your projects, the normalizer injects direct URLs so Claude can say "Here is your project: Q1 Planning" instead of dumping raw JSON. When an agent is created, the normalizer adds the public embed URL. Every response becomes actionable.

The result: Taskade users can manage their entire workspace through natural language in Claude Desktop or Cursor — creating projects, assigning tasks, training agents, and triggering automations — all through MCP tools that were auto-generated from a single OpenAPI spec.

Competitive Landscape: OpenAPI-to-MCP Tools in 2026

The MCP ecosystem is growing fast. Here is how every major approach to OpenAPI-to-MCP conversion compares:

When to use each:

• @taskade/mcp-openapi-codegen — You want inspectable, committable TypeScript with full customization. You have a Node.js codebase and want zero vendor lock-in. You need response normalizers.
• openapi-mcp-generator — Quick start for simple APIs. Good community momentum (500+ stars).
• AWS openapi-mcp-server — You trust AWS, need dynamic tool creation at runtime without a build step.
• FastMCP — You are in the Python ecosystem and want a Pythonic developer experience.
• Speakeasy / Stainless — Enterprise teams with complex APIs, budget for managed services, and need OAuth2 flows handled automatically.

Production Hardening

Generating tools is step one. Running them safely in production requires attention to security, reliability, and observability.

Security

┌──────────────────────────────────────────────────────┐
│                                                      │
│   MCP SECURITY CHECKLIST                             │
│                                                      │
│   ☐ Scope tokens to minimum required permissions     │
│   ☐ Use allowlists — never expose all endpoints      │
│   ☐ Validate inputs with Zod schemas (built-in)      │
│   ☐ Sanitize responses to prevent data leakage       │
│   ☐ Rate limit tool calls at the server level        │
│   ☐ Log every tool invocation for audit trails       │
│   ☐ Never embed secrets in generated code            │
│   ☐ Use environment variables for all credentials    │
│                                                      │
└──────────────────────────────────────────────────────┘

MCP servers run with the privileges of the API tokens they hold. In January 2026, security researchers disclosed critical vulnerabilities in several popular MCP servers — including prompt injection paths and SSRF vectors. The lesson: treat your MCP server as a production service, not a toy.

The generated Zod schemas from @taskade/mcp-openapi-codegen provide input validation out of the box. But you should also: (1) scope your API tokens to the minimum required permissions, (2) use allowlists to limit which endpoints are exposed, and (3) sanitize any response data that could contain sensitive information.

Error Handling

Wrap your fetchFn with retry logic and structured error responses:

fetchFn: async (url, init) => {
  const response = await fetch(url, { ...init, signal: AbortSignal.timeout(10000) });
  if (!response.ok) {
    const error = await response.text();
    throw new Error(`API error ${response.status}: ${error}`);
  }
  return response;
}

Monitoring

Log every tool call with structured metadata — operation name, latency, status code, and input parameters (minus sensitive values). This gives you observability into how AI agents use your API and which tools see the most traffic.

What's Next: MCP Ecosystem in 2026

The MCP ecosystem is evolving rapidly:

• Streamable HTTP transport is replacing SSE as the preferred remote transport, enabling stateless MCP servers that scale horizontally.
• The OpenAPI Initiative's Moonwalk SIG is working on making API specifications natively "agent-ready" — richer descriptions, semantic annotations, and tool-level metadata baked into the spec itself.
• Remote MCP servers (hosted, authenticated, shared across clients) are becoming the deployment model for production use cases, replacing local stdio servers.
• Agentic AI Foundation (under the Linux Foundation) now governs the MCP specification, ensuring vendor-neutral evolution.

The direction is clear: every API will need an MCP interface. The question is whether you write 5,600 lines of boilerplate by hand or let a codegen tool do it in 10 seconds.

Quick Start Checklist

┌──────────────────────────────────────────────────────┐
│                                                      │
│   GET STARTED IN 5 MINUTES                           │
│                                                      │
│   1. $ npm install @taskade/mcp-openapi-codegen      │
│   2. Point specPath at your OpenAPI spec              │
│   3. $ npx tsx generate-mcp-tools.ts                  │
│   4. Create MCP server with registerTools()           │
│   5. Add to Claude Desktop / Cursor config            │
│   6. Start talking to your API                        │
│                                                      │
│   GitHub: github.com/taskade/mcp                      │
│   npm:    @taskade/mcp-openapi-codegen                │
│                                                      │
└──────────────────────────────────────────────────────┘

Frequently Asked Questions

Related Reading

Taskade Developer Resources:

• GitHub: taskade/mcp — Source code, examples, and documentation
• npm: @taskade/mcp-openapi-codegen — The codegen package
• npm: @taskade/mcp-server — Taskade's production MCP server
• Taskade API Documentation — The API spec this codegen powers

MCP Ecosystem:

• Model Context Protocol — Official Site
• MCP Specification
• awesome-mcp-servers — 30K+ star community directory

From the Taskade Blog:

• How to Build Your First AI Agent in 60 Seconds — Getting started with AI agents
• Best AI Agent Builders in 2026 — Comparison of agent platforms
• How to Build AI Agents Faster — Speed up agent development
• Best Vibe Coding Tools 2026 — Compare AI development tools
• The Ultimate Guide to Taskade Genesis — Complete platform reference
• What Is Vibe Coding? — The new era of building software with natural language

Explore Taskade:

• AI Agent Builder — Create intelligent AI teammates with custom tools
• AI App Builder — Build complete apps from one prompt
• Automation Workflows — Connect 100+ integrations
• Community Gallery — 150,000+ apps to clone