MCP with Next.js - Integration Guide

Overview

This guide shows how to connect a Next.js API to Claude Desktop through MCP. The workflow is: generate OpenAPI, create an MCP server with LegacyAI, and register the tool catalog in Claude Desktop.

OpenAPI generation options

Teams commonly use next-openapi-gen, openapi-typescript, or a custom script that inspects route handlers. The key is to produce a single OpenAPI file that includes all routes, parameters, and response schemas.

If you use both App Router and Pages Router APIs, merge them into one spec so the MCP server can expose a unified tool catalog.

Step 1: Generate OpenAPI from Next.js

Use a tool like next-openapi-gen or a custom script to export OpenAPI for your API routes. Ensure request and response schemas are defined for reliable tool generation.

Step 2: Validate the spec

Run an OpenAPI validator to confirm required fields, auth schemes, and request bodies. Clean specs yield better MCP tools.

Step 3: Generate MCP tools with LegacyAI

Upload the OpenAPI file to LegacyAI to generate an MCP server. Review tools, enable read-only defaults, and configure auth mapping before publishing.

Step 4: Configure Claude Desktop

Add the MCP server to Claude Desktop so the tools appear and can be called directly.

{
  "mcpServers": [
    {
      "name": "LegacyAI Next.js",
      "command": "node",
      "args": ["./legacyai-mcp-server.js"],
      "env": {
        "API_BASE_URL": "https://api.yourcompany.com",
        "API_TOKEN": "${API_TOKEN}"
      }
    }
  ]
}

Step 5: Test tool calls

Start with a read-only endpoint to confirm access. Review logs to verify parameters and responses are validated correctly.

CI/CD sync strategy

Add a pipeline step that exports OpenAPI and triggers MCP regeneration only when API files change. This keeps the tool catalog aligned without regenerating on every build.

If you deploy multiple environments, generate separate MCP servers so each environment has isolated credentials and tool scopes.

Deployment considerations

Run the MCP server as a separate service, not as part of your Next.js runtime. This isolates failures and keeps your application deployment lightweight.

Use environment variables or a secrets manager for tokens, and configure rate limits to prevent excessive tool calls.

Common pitfalls

• Missing request body schemas on POST or PATCH routes.
• Auth schemes declared in code but not in the spec.
• Responses without clear schema definitions.
• Mixed base URLs across environments.