Add OpenAPI Adapter

The OpenAPI Adapter automatically converts REST API endpoints defined in an OpenAPI 3.x specification into fully-functional MCP tools. This guide walks you through adding the adapter to your app.

Prerequisites:

A FrontMCP project initialized (see Installation)
An OpenAPI 3.x specification (URL or local file)
Basic understanding of REST APIs

What You’ll Build

By the end of this guide, you’ll have:

✅ An app that automatically generates tools from an OpenAPI spec
✅ Type-safe input validation for all API endpoints
✅ Authentication configured for API requests
✅ Tools that inherit all your app-level plugins and providers

The OpenAPI Adapter is perfect for quickly exposing REST APIs to AI agents without writing custom tool code for each endpoint.

Step 1: Install the Adapter

npm install @frontmcp/adapters

pnpm add @frontmcp/adapters

yarn add @frontmcp/adapters

Step 2: Add Adapter to Your App

Create or update your app to include the OpenAPI adapter:

import { App } from '@frontmcp/sdk';
import { OpenapiAdapter } from '@frontmcp/adapters';

@App({
  id: 'expense',
  name: 'Expense MCP App',
  adapters: [
    OpenapiAdapter.init({
      name: 'expense-api',
      baseUrl: 'https://api.example.com',
      url: 'https://api.example.com/openapi.json',
    }),
  ],
})
export default class ExpenseApp {}

import { App } from '@frontmcp/sdk';
import { OpenapiAdapter } from '@frontmcp/adapters';
import spec from './openapi.json';

@App({
  id: 'expense',
  name: 'Expense MCP App',
  adapters: [
    OpenapiAdapter.init({
      name: 'expense-api',
      baseUrl: 'https://api.example.com',
      spec: spec, // Direct JSON import supported
    }),
  ],
})
export default class ExpenseApp {}

import { App } from '@frontmcp/sdk';
import { OpenapiAdapter } from '@frontmcp/adapters';

@App({
  id: 'expense',
  name: 'Expense MCP App',
  adapters: [
    OpenapiAdapter.init({
      name: 'expense-api',
      baseUrl: 'https://api.example.com',
      url: 'https://api.example.com/openapi.json',
      additionalHeaders: {
        'x-api-key': process.env.API_KEY!,
      },
    }),
  ],
})
export default class ExpenseApp {}

Step 3: Configure Your Server

Add your app to the FrontMCP server:

src/main.ts

import { FrontMcp, LogLevel } from '@frontmcp/sdk';
import ExpenseApp from './apps/expense.app';

@FrontMcp({
  info: { name: 'Expense Server', version: '1.0.0' },
  apps: [ExpenseApp],
  http: { port: 3000 },
  logging: { level: LogLevel.INFO },
})
export default class Server {}

Step 4: Run and Test

Start the server

npm run dev

The server will load the OpenAPI spec and generate tools for each operation.

Verify tools are loaded

Check the console output for messages like: [INFO] Generated 15 tools from expense-api [INFO] Server listening on http://localhost:3000

Test with Inspector

npm run inspect

Open the MCP Inspector and you’ll see all generated tools from your API spec!

Understanding Generated Tools

Each OpenAPI operation becomes a tool with:

Tool Naming

Tools are named using the pattern: {adapter-name}:{method}_{path} For example:

GET /users → expense-api:get_users
POST /expenses → expense-api:post_expenses
GET /expenses/{id} → expense-api:get_expenses_id

If your OpenAPI spec includes operationId, that will be used instead of the generated name.

Input Schema

The adapter automatically converts OpenAPI parameters to Zod schemas:

OpenAPI spec

paths:
  /expenses:
    post:
      parameters:
        - name: category
          in: query
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                description:
                  type: string

Becomes a tool with this input:

{
  category: string,    // from query parameter
  amount: number,      // from request body
  description: string  // from request body
}

Advanced Configuration

For comprehensive documentation on all configuration options including inputTransforms, toolTransforms, descriptionMode, and the x-frontmcp OpenAPI extension, see the full OpenAPI Adapter documentation.

Filter Operations

Only include specific endpoints:

OpenapiAdapter.init({
  name: 'billing-api',
  baseUrl: 'https://api.example.com',
  url: 'https://api.example.com/openapi.json',
  generateOptions: {
    // Only include operations starting with /invoices or /customers
    filterFn: (op) => op.path.startsWith('/invoices') || op.path.startsWith('/customers'),
  },
});

User-Based Authentication

Use authenticated user context for API requests:

OpenapiAdapter.init({
  name: 'user-api',
  baseUrl: 'https://api.example.com',
  url: 'https://api.example.com/openapi.json',
  headersMapper: (ctx, headers) => {
    // Add user's token to API requests
    if (ctx.authInfo?.token) {
      headers.set('authorization', `Bearer ${ctx.authInfo.token}`);
    }
    return headers;
  },
});

Multi-Tenant Setup

Include tenant ID from user context:

OpenapiAdapter.init({
  name: 'tenant-api',
  baseUrl: 'https://api.example.com',
  url: 'https://api.example.com/openapi.json',
  headersMapper: (ctx, headers) => {
    // Add tenant ID header
    if (ctx.authInfo?.user?.tenantId) {
      headers.set('x-tenant-id', ctx.authInfo.user.tenantId);
    }
    return headers;
  },
  bodyMapper: (ctx, body) => {
    // Add tenant ID to all request bodies
    return {
      ...body,
      tenantId: ctx.authInfo?.user?.tenantId,
    };
  },
});

How It Works

Load Spec

The adapter fetches and parses the OpenAPI specification from the URL or uses the provided spec object

Generate Tools

Each operation in the spec becomes an MCP tool with: - Automatic input schema (path params, query params, headers, body) - Type-safe validation using Zod - Description from the operation summary

Generated tools are registered with your app and inherit: - App-level plugins (caching, logging, etc.) - App-level providers - App-level authentication

Execute Requests

When a tool is called:

Input is validated against the schema
Headers/body are mapped (if configured)
HTTP request is made to the API
Response is parsed and returned

Common Patterns

Expose multiple APIs

Add multiple adapters to one app:

@App({
  id: 'integrations',
  name: 'Third-Party Integrations',
  adapters: [
    OpenapiAdapter.init({
      name: 'github',
      baseUrl: 'https://api.github.com',
      url: 'https://api.github.com/openapi.json',
    }),
    OpenapiAdapter.init({
      name: 'slack',
      baseUrl: 'https://api.slack.com',
      url: 'https://api.slack.com/openapi.json',
    }),
  ],
})

Combine with custom tools

Mix generated and hand-written tools:

import CustomTool from './tools/custom.tool';

@App({
  id: 'hybrid',
  name: 'Hybrid App',
  tools: [CustomTool], // Hand-written
  adapters: [
    OpenapiAdapter.init({...}), // Auto-generated
  ],
})

Apply plugins to generated tools

Generated tools inherit app plugins:

Note: Requires the optional @frontmcp/plugin-cache package. Install it first:
npm install @frontmcp/plugin-cache

import { CachePlugin } from '@frontmcp/plugin-cache';

@App({
  id: 'cached-api',
  name: 'Cached API',
  plugins: [
    CachePlugin.init({
      type: 'redis',
      defaultTTL: 300,
    }),
  ],
  adapters: [
    OpenapiAdapter.init({...}),
  ],
})

Now all generated tools can use caching!

Troubleshooting

No tools generated

Possible causes:

Invalid OpenAPI spec URL
Spec is OpenAPI 2.0 (only 3.x supported)
All operations filtered out by filterFn

Solutions:

Verify the URL is accessible
Convert OpenAPI 2.0 to 3.x using Swagger Editor
Check your filter configuration

Authentication errors (401)

Possible causes:

Missing or invalid API credentials
Headers not properly mapped

Solutions:

Verify additionalHeaders or headersMapper configuration
Check that authInfo.token contains the expected value
Test the API directly with curl/Postman first

Tools have unexpected inputs

Possible cause:

OpenAPI spec has complex parameter definitions

Solution:

Use inputTransforms to transform the input at request time. See the full OpenAPI Adapter documentation for details.

What’s Next?

Full OpenAPI Adapter Docs

Explore all configuration options and advanced features

Authentication Setup

Learn how to configure authentication for your APIs

Plugin System

Add caching, logging, and other features to generated tools

Demo App

See a complete example using the OpenAPI adapter

Complete Example

Here’s a full working example with authentication and caching:

import { FrontMcp, App, LogLevel } from '@frontmcp/sdk';
import { OpenapiAdapter } from '@frontmcp/adapters';
import { CachePlugin } from '@frontmcp/plugin-cache';

@App({
  id: 'expense',
  name: 'Expense Management',
  plugins: [
    CachePlugin.init({
      type: 'redis',
      defaultTTL: 300, // 5 minutes
      config: {
        host: 'localhost',
        port: 6379,
      },
    }),
  ],
  adapters: [
    OpenapiAdapter.init({
      name: 'expense-api',
      baseUrl: process.env.API_BASE_URL!,
      url: process.env.OPENAPI_SPEC_URL!,
      headersMapper: (ctx, headers) => {
        // Add user's JWT token
        if (ctx.authInfo?.token) {
          headers.set('authorization', `Bearer ${ctx.authInfo.token}`);
        }
        // Add tenant ID
        if (ctx.authInfo?.user?.tenantId) {
          headers.set('x-tenant-id', ctx.authInfo.user.tenantId);
        }
        return headers;
      },
      bodyMapper: (ctx, body) => {
        // Add user context to mutations
        return {
          ...body,
          createdBy: ctx.authInfo?.user?.id,
          tenantId: ctx.authInfo?.user?.tenantId,
        };
      },
      generateOptions: {
        // Only expose expense-related endpoints
        filterFn: (op) => op.path.startsWith('/expenses'),
      },
    }),
  ],
})
class ExpenseApp {}

@FrontMcp({
  info: { name: 'Expense Server', version: '1.0.0' },
  apps: [ExpenseApp],
  http: { port: 3000 },
  logging: { level: LogLevel.INFO },
  auth: {
    type: 'remote',
    name: 'auth-provider',
    baseUrl: process.env.AUTH_BASE_URL!,
  },
})
export default class Server {}

Get Started

Concepts

Build

Deploy

Plugins

Adapters

Extensibility

Testing

React SDK

Guides

What You’ll Build

Step 1: Install the Adapter

Step 2: Add Adapter to Your App

Step 3: Configure Your Server

Step 4: Run and Test

Understanding Generated Tools

Tool Naming

Input Schema

Advanced Configuration

Filter Operations

User-Based Authentication

Multi-Tenant Setup

How It Works

Common Patterns

Troubleshooting

What’s Next?

Full OpenAPI Adapter Docs

Authentication Setup

Plugin System

Demo App

Complete Example

​What You’ll Build

​Step 1: Install the Adapter

​Step 2: Add Adapter to Your App

​Step 3: Configure Your Server

​Step 4: Run and Test

​Understanding Generated Tools

​Tool Naming

​Input Schema

​Advanced Configuration

​Filter Operations

​User-Based Authentication

​Multi-Tenant Setup

​How It Works

​Common Patterns

​Troubleshooting

​What’s Next?

Full OpenAPI Adapter Docs

Authentication Setup

Plugin System

Demo App

​Complete Example

What You’ll Build

Step 1: Install the Adapter

Step 2: Add Adapter to Your App

Step 3: Configure Your Server

Step 4: Run and Test

Understanding Generated Tools

Tool Naming

Input Schema

Advanced Configuration

Filter Operations

User-Based Authentication

Multi-Tenant Setup

How It Works

Common Patterns

Troubleshooting

What’s Next?

Complete Example