OpenAPI Adapter - AgentFront

The OpenAPI Adapter automatically converts OpenAPI 3.x specifications into fully-functional MCP tools. Each API operation becomes a callable tool with built-in validation, authentication, and type safety.

Wrapping a large API (50+ operations)? The flat-exposure model the adapter uses hits the well-documented “tool overload” wall — Claude reliability degrades past ~20 tools, GPT Actions caps at 30. Consider the Skilled OpenAPI plugin instead, which curates operations into named skills behind three meta-tools and supports CI-signed bundle delivery. See the coexistence guide for running both in the same server.

Why use it

Zero boilerplate — Turn REST APIs into MCP tools without writing glue code
Type-safe — Automatic Zod schema generation from OpenAPI specs
Multi-auth support — Built-in support for multiple authentication providers
Production-ready — Comprehensive security validation and error handling
Flexible — Filter operations, customize schemas, and inject custom logic

Installation

npm install @frontmcp/adapters

Quick start

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

@App({
  id: 'my-api',
  name: 'My API MCP Server',
  adapters: [
    OpenapiAdapter.init({
      name: 'backend:api',
      baseUrl: process.env.API_BASE_URL!,
      url: process.env.OPENAPI_SPEC_URL!,
    }),
  ],
})
export default class MyApiApp {}

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

@App({
  id: 'my-api',
  name: 'My API MCP Server',
  adapters: [
    OpenapiAdapter.init({
      name: 'backend:api',
      baseUrl: process.env.API_BASE_URL!,
      url: process.env.OPENAPI_SPEC_URL!,
      additionalHeaders: {
        'x-api-key': process.env.API_KEY!,
      },
    }),
  ],
})
export default class MyApiApp {}

Configuration

Required Options

string

required

Unique identifier for this adapter instance. Used to prefix tool names when multiple adapters are present.

string

required

Base URL for API requests (e.g., https://api.example.com/v1).

OpenAPIV3.Document | OpenAPIV3_1.Document | object

In-memory OpenAPI specification object. Accepts typed documents or plain objects from JSON imports. Use either spec or url, not both.

string

URL or file path to the OpenAPI specification. Can be a local file path or remote URL. Use either spec or url, not both.

Optional Configuration

Record<string, string>

Static headers applied to every request. Useful for API keys or static authentication tokens.

(ctx: FrontMcpContext, headers: Headers) => Headers

Function to dynamically set headers based on request context. Access ctx.authInfo, ctx.sessionId, ctx.traceContext, etc. Headers set here are hidden from MCP clients.

(ctx: FrontMcpContext, body: any) => any

Function to transform or augment the request body before sending. Access ctx.authInfo, ctx.sessionId, etc. Useful for adding tenant IDs or user-specific data.

LoadOptions

Options for loading the OpenAPI specification — headers, timeout, validation, and $ref resolution security. See refResolution for controlling how external $ref pointers are resolved.

GenerateOptions

Options for tool generation — filtering, naming, schema depth, format resolution, and more. See Advanced Features and Format Resolution for details.

InputTransformOptions

Hide inputs from the schema and inject values at request time. Supports global, per-tool, and generator-based transforms. See Input Schema Transforms.

ToolTransformOptions

Customize generated tools with annotations, tags, descriptions, and more. Supports global, per-tool, and generator-based transforms. See Tool Transforms.

SchemaTransformOptions

Modify input/output schema definitions at fetch() time. Use schemaTransforms.input and schemaTransforms.output for global, per-tool, or generator-based transforms.

OutputSchemaOptions

Control where and how output schema is exposed: mode ('definition' | 'description' | 'both'), descriptionFormat ('jsonSchema' | 'summary'), and a custom descriptionFormatter.

DataTransformOptions

Transform tool definitions and API response data. Supports preToolTransforms (schema-level) and postToolTransforms (response-level), each with global, per-tool, and generator forms. See Data Transforms.

SpecPollerOptions & { enabled: boolean }

Enable live polling to auto-detect spec changes and rebuild tools at runtime. Requires url option (not spec). See Polling & Live Updates for full configuration reference.

'summaryOnly' | 'descriptionOnly' | 'combined' | 'full'

How to generate tool descriptions from OpenAPI operations. Default: 'summaryOnly'.

FrontMcpLogger

Logger instance for adapter diagnostics. When using OpenapiAdapter.init() within a FrontMCP app, the SDK automatically provides the logger via setLogger(). For standalone usage, you can optionally provide a logger implementing the FrontMcpLogger interface; if omitted, a console-based logger is created automatically.

Authentication

The OpenAPI adapter provides multiple authentication strategies with different security risk levels. Choose the approach that best fits your use case.

Strategy 1: Static Headers (Medium Risk)

Best for: Server-to-server APIs with static credentials.

OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  additionalHeaders: {
    'x-api-key': process.env.API_KEY!,
    authorization: `Bearer ${process.env.API_TOKEN}`,
  },
});

Store credentials in environment variables or secrets manager, never hardcode them.

Strategy 2: Auth Provider Mapper (Low Risk) ⭐ Recommended

Best for: Multi-provider authentication (GitHub, Slack, Google, etc.). This approach maps OpenAPI security scheme names to authentication extractors. Each security scheme can use a different auth provider from the authenticated user context.

OpenapiAdapter.init({
  name: 'multi-auth-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  authProviderMapper: {
    // Map security scheme 'GitHubAuth' to GitHub token from user context
    GitHubAuth: (ctx) => ctx.authInfo.user?.githubToken,

    // Map security scheme 'SlackAuth' to Slack token from user context
    SlackAuth: (ctx) => ctx.authInfo.user?.slackToken,

    // Map security scheme 'ApiKeyAuth' to API key from user context
    ApiKeyAuth: (ctx) => ctx.authInfo.user?.apiKey,
  },
});

How it works:

Extracts security scheme names from OpenAPI spec (e.g., GitHubAuth, SlackAuth)
For each tool, looks up the required security scheme
Calls the corresponding extractor function to get the token from ctx.authInfo
Applies the token to the request

Security Risk: LOW — Authentication is resolved from the request context, not exposed to MCP clients.

The ctx parameter in authProviderMapper, headersMapper, bodyMapper, and securityResolver callbacks is the FrontMcpContext containing authInfo, sessionId, traceContext, and more. By the time your tool executes, authentication has been verified and auth fields are populated.

Strategy 3: Custom Security Resolver (Low Risk)

Best for: Complex authentication logic or custom security requirements.

OpenapiAdapter.init({
  name: 'custom-auth-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  securityResolver: (tool, ctx) => {
    const authInfo = ctx.authInfo;

    // Use GitHub token for GitHub API tools
    if (tool.name.startsWith('github_')) {
      return { jwt: authInfo.user?.githubToken };
    }

    // Use Google token for Google API tools
    if (tool.name.startsWith('google_')) {
      return { jwt: authInfo.user?.googleToken };
    }

    // Use API key for admin tools
    if (tool.name.startsWith('admin_')) {
      return { apiKey: authInfo.user?.adminApiKey };
    }

    // Default to main JWT token
    return { jwt: authInfo.token };
  },
});

Security Risk: LOW — Full control over authentication resolution from request context.

Strategy 4: Static Auth (Medium Risk)

Best for: Server-to-server APIs where credentials don’t change per user.

OpenapiAdapter.init({
  name: 'backend-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  staticAuth: {
    jwt: process.env.API_JWT_TOKEN,
    apiKey: process.env.API_KEY,
  },
});

Security Risk: MEDIUM — Store credentials securely in environment variables or secrets manager.

Strategy 5: Dynamic Headers & Body Mapping (Low Risk)

Best for: Adding user-specific data (tenant IDs, user IDs) to requests.

OpenapiAdapter.init({
  name: 'tenant-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  headersMapper: (ctx, headers) => {
    const authInfo = ctx.authInfo;

    // Add authorization header
    if (authInfo.token) {
      headers.set('authorization', `Bearer ${authInfo.token}`);
    }

    // Add tenant ID from user context
    if (authInfo.user?.tenantId) {
      headers.set('x-tenant-id', authInfo.user.tenantId);
    }

    // Add trace ID for distributed tracing
    headers.set('x-trace-id', ctx.traceContext.traceId);

    return headers;
  },
  bodyMapper: (ctx, body) => {
    const authInfo = ctx.authInfo;

    // Add user ID to all request bodies
    return {
      ...body,
      createdBy: authInfo.user?.id,
      tenantId: authInfo.user?.tenantId,
    };
  },
});

Security Risk: LOW — User-specific data is injected server-side, hidden from MCP clients.

Default Behavior (Medium Risk)

If no authentication configuration is provided, the adapter uses authInfo.token for all Bearer auth schemes.

OpenapiAdapter.init({
  name: 'simple-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  // No auth config - will use authInfo.token by default
});

Security Risk: MEDIUM — Only works for single Bearer auth. For multiple auth providers, use authProviderMapper or securityResolver.

Advanced Features

Filtering Operations

Control which API operations become MCP tools.

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

OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  generateOptions: {
    excludeOperations: ['deprecatedEndpoint', 'internalOnly'],
  },
});

OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  generateOptions: {
    includeOperations: ['getUser', 'createUser', 'updateUser'],
  },
});

Input Schema Transformation

Customize the input schema definition for generated tools using schemaTransforms.input:

OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  schemaTransforms: {
    input: {
      global: (schema) => {
        // Remove sensitive fields from the input schema
        if (schema.properties?.password) {
          delete schema.properties.password;
        }

        // Add custom fields
        schema.properties = {
          ...schema.properties,
          customField: {
            type: 'string',
            description: 'Custom field added by transform',
          },
        };

        return schema;
      },
    },
  },
});

Input Schema Transforms

Hide inputs from AI/users and inject values server-side at request time. This is more powerful than schemaTransforms.input because it provides access to the authentication context.

OpenapiAdapter.init({
  name: 'tenant-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  inputTransforms: {
    global: [
      // Hide tenant header from AI, inject from user context
      // The injector receives { ctx, env, tool } — destructure ctx for FrontMcpContext
      { inputKey: 'X-Tenant-Id', inject: ({ ctx }) => ctx.authInfo.user?.tenantId },
      // Add correlation ID to all requests
      { inputKey: 'X-Correlation-Id', inject: () => crypto.randomUUID() },
    ],
  },
});

OpenapiAdapter.init({
  name: 'audit-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  inputTransforms: {
    perTool: {
      'createAuditLog': [
        { inputKey: 'userId', inject: ({ ctx }) => ctx.authInfo.user?.id },
        { inputKey: 'timestamp', inject: () => new Date().toISOString() },
      ],
    },
  },
});

OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  inputTransforms: {
    generator: (tool) => {
      // Add request ID to all mutating operations
      if (['post', 'put', 'patch', 'delete'].includes(tool.metadata.method)) {
        return [{ inputKey: 'X-Request-Id', inject: () => crypto.randomUUID() }];
      }
      return [];
    },
  },
});

Security Benefit: Sensitive inputs like tenant IDs and user IDs are injected server-side, never exposed to MCP clients.

Tool Transforms

Customize generated tools with annotations, tags, descriptions, and more.

OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  toolTransforms: {
    global: {
      annotations: { openWorldHint: true },
    },
  },
});

OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  toolTransforms: {
    perTool: {
      'createUser': {
        annotations: { destructiveHint: false },
        tags: ['user-management'],
      },
      'deleteUser': {
        annotations: { destructiveHint: true },
        tags: ['user-management', 'dangerous'],
      },
    },
  },
});

OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  toolTransforms: {
    generator: (tool) => {
      // Auto-annotate based on HTTP method
      if (tool.metadata.method === 'get') {
        return { annotations: { readOnlyHint: true, destructiveHint: false } };
      }
      if (tool.metadata.method === 'delete') {
        return { annotations: { destructiveHint: true } };
      }
      return undefined;
    },
  },
});

Available transform properties:

Property	Type	Description
`name`	`string \| function`	Override or transform the tool name
`description`	`string \| function`	Override or transform the tool description
`annotations`	`ToolAnnotations`	MCP tool behavior hints
`tags`	`string[]`	Categorization tags
`examples`	`ToolExample[]`	Usage examples
`hideFromDiscovery`	`boolean`	Hide tool from listing
`ui`	`ToolUIConfig`	UI configuration for tool forms

Output Schema Display

Control how output schemas appear in tool definitions via the outputSchema option:

OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  outputSchema: {
    mode: 'description',           // 'definition' | 'description' | 'both'
    descriptionFormat: 'summary',  // 'jsonSchema' | 'summary'
  },
});

Field	Type	Description
`mode`	`'definition' \| 'description' \| 'both'`	Where to expose the schema. Default: `'definition'`.
`descriptionFormat`	`'jsonSchema' \| 'summary'`	Format used when schema appears in description. Default: `'summary'`.
`descriptionFormatter`	`(schema, ctx) => string \| Promise<string>`	Custom formatter (sync or async, e.g., LLM-generated).

Custom Schema Formatter

Provide your own formatter (can be async to support LLM-based generation):

OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  outputSchema: {
    mode: 'description',
    descriptionFormatter: async (schema, ctx) => {
      // ctx.tool, ctx.adapterOptions, ctx.originalDescription available
      return `Response: ${JSON.stringify(schema.properties || {})}`;
    },
  },
});

Data Transforms

Transform tool definitions and API response data via dataTransforms:

Pre-Tool Transforms (Schema Level)

Modify schemas and descriptions before tools are wrapped — applied during fetch() to McpOpenAPITool definitions:

OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  dataTransforms: {
    preToolTransforms: {
      global: {
        transformSchema: (outputSchema, ctx) => undefined, // remove from all
        transformDescription: (desc, outputSchema, ctx) =>
          outputSchema ? `${desc}\n\nReturns: ${JSON.stringify(outputSchema)}` : desc,
      },
    },
  },
});

OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  dataTransforms: {
    preToolTransforms: {
      perTool: {
        listUsers: {
          transformDescription: (desc) => `${desc}\n\nPaginated list of users.`,
        },
        getUser: {
          transformSchema: (schema) => schema && { ...schema, description: 'User object with profile data' },
        },
      },
    },
  },
});

OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  dataTransforms: {
    preToolTransforms: {
      generator: (tool) => {
        if (tool.metadata.method === 'get') {
          return {
            transformSchema: () => undefined,
            transformDescription: (desc, schema) =>
              schema ? `${desc}\n\n---\nOutput: ${JSON.stringify(schema)}` : desc,
          };
        }
        return undefined;
      },
    },
  },
});

Post-Tool Transforms (Response Level)

Transform API response data at runtime:

OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  dataTransforms: {
    postToolTransforms: {
      global: {
        transform: (data) => ({ ...(data as object), _transformedAt: new Date().toISOString() }),
      },
    },
  },
});

OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  dataTransforms: {
    postToolTransforms: {
      perTool: {
        listUsers: {
          transform: (data) => (data as any)?.users ?? data,
        },
        getUser: {
          transform: (data) => ({
            ...(data as any),
            fullName: `${(data as any)?.firstName} ${(data as any)?.lastName}`,
          }),
        },
      },
    },
  },
});

OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  dataTransforms: {
    postToolTransforms: {
      global: {
        filter: (ctx) => ctx.ok && ctx.status === 200,
        transform: (data) => ({ result: data }),
      },
    },
  },
});

Post-tool transform context:

Property	Type	Description
`ctx`	`FrontMcpContext`	Full request context
`tool`	`McpOpenAPITool`	Tool definition
`status`	`number`	HTTP response status code
`ok`	`boolean`	Whether response was successful
`adapterOptions`	`object`	Adapter configuration

Error Handling: Transform failures are logged and the original data is returned, ensuring graceful degradation.

x-frontmcp OpenAPI Extension

Configure tool behavior directly in your OpenAPI spec using the x-frontmcp extension:

openapi.yaml

paths:
  /users:
    get:
      operationId: listUsers
      summary: List all users
      x-frontmcp:
        annotations:
          readOnlyHint: true
          idempotentHint: true
        cache:
          ttl: 300
        tags:
          - users
          - public-api
    delete:
      operationId: deleteUser
      summary: Delete a user
      x-frontmcp:
        annotations:
          destructiveHint: true
        tags:
          - users
          - dangerous

Extension properties:

Property	Type	Description
`annotations`	`object`	Tool behavior hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint, title)
`cache`	`object`	Cache config: `ttl` (seconds), `slideWindow` (boolean)
`codecall`	`object`	CodeCall config: `enabledInCodeCall`, `visibleInListTools`
`tags`	`string[]`	Categorization tags
`hideFromDiscovery`	`boolean`	Hide from tool listing
`examples`	`array`	Usage examples with input/output

Use x-frontmcp in your OpenAPI spec for declarative configuration. Use toolTransforms in adapter config to override spec values.

Description Mode

Control how tool descriptions are generated from OpenAPI operations:

OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  descriptionMode: 'combined', // Default: 'summaryOnly'
});

Mode	Description
`'summaryOnly'`	Use only the OpenAPI summary (default)
`'descriptionOnly'`	Use only the OpenAPI description
`'combined'`	Summary followed by description
`'full'`	Summary, description, and operation details

Format Resolution

Enrich generated tool schemas with concrete constraints derived from OpenAPI format values. When enabled, formats like uuid, date-time, email, int32, etc. are expanded into patterns, descriptions, and min/max constraints.

OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  generateOptions: {
    resolveFormats: true,
  },
});
// A field with format: "uuid" gets pattern: "^[0-9a-f]{8}-..." added
// A field with format: "int32" gets minimum/maximum constraints
// A field with format: "email" gets a pattern and description

OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  generateOptions: {
    resolveFormats: true, // Include built-in resolvers
    formatResolvers: {
      // Add or override format resolvers
      'phone': (schema) => ({
        ...schema,
        pattern: '^\\+[1-9]\\d{1,14}$',
        description: 'E.164 phone number',
      }),
      'currency': (schema) => ({
        ...schema,
        pattern: '^[A-Z]{3}$',
        description: 'ISO 4217 currency code',
      }),
    },
  },
});

OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  generateOptions: {
    // Without resolveFormats, only custom resolvers are applied
    formatResolvers: {
      'phone': (schema) => ({
        ...schema,
        pattern: '^\\+[1-9]\\d{1,14}$',
      }),
    },
  },
});

Option	Type	Default	Description
`resolveFormats`	`boolean`	`false`	Enable built-in format resolvers (uuid, date-time, email, int32, etc.)
`formatResolvers`	`Record<string, FormatResolver>`	`undefined`	Custom format resolvers. When used with `resolveFormats: true`, custom resolvers are merged with built-ins (custom takes precedence).

Format resolution improves tool input validation by giving AI models concrete constraints. For example, a uuid field gets a regex pattern, helping the model generate valid values.

Load Options

Configure how the OpenAPI spec is loaded.

OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  baseUrl: 'https://api.example.com',
  loadOptions: {
    headers: {
      authorization: `Bearer ${process.env.SPEC_ACCESS_TOKEN}`,
    },
    timeout: 10000, // 10 seconds
  },
});

$ref Resolution Security

Security Advisory (GHSA-v6ph-xcq9-qxxj): In mcp-from-openapi versions ≤ 2.1.2, external $ref pointers in OpenAPI specs were resolved without restrictions, enabling SSRF attacks (cloud metadata theft, internal network scanning, local file reads). Upgrade to mcp-from-openapi ≥ 2.2.0 for built-in protection.

When the adapter dereferences $ref pointers in your OpenAPI spec, it enforces security restrictions by default:

file:// protocol is blocked — prevents local file reads (e.g., $ref: "file:///etc/passwd")
Internal/private IPs are blocked — prevents SSRF to cloud metadata endpoints and internal services
http:// and https:// to public hosts are allowed — external schema references work normally

The blocked IP ranges include: 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16 (cloud metadata), ::1, fd00::/8, and hostnames localhost, metadata.google.internal. Configure via loadOptions.refResolution:

// Default behavior — no configuration needed.
// file:// blocked, internal IPs blocked, http/https to public hosts allowed.
OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
});

// Only allow $refs pointing to your own schema servers
OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  loadOptions: {
    refResolution: {
      allowedHosts: ['schemas.example.com', 'api.example.com'],
    },
  },
});

// Enable file:// for specs that reference local schema files
OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  loadOptions: {
    refResolution: {
      allowedProtocols: ['http', 'https', 'file'],
    },
  },
});

// WARNING: Only use in trusted environments (e.g., internal APIs)
OpenapiAdapter.init({
  name: 'internal-api',
  url: 'http://10.0.0.5:8080/openapi.json',
  loadOptions: {
    refResolution: {
      allowInternalIPs: true,
    },
  },
});

// Only resolve local #/ JSON pointer refs, block everything external
OpenapiAdapter.init({
  name: 'my-api',
  url: 'https://api.example.com/openapi.json',
  loadOptions: {
    refResolution: {
      allowedProtocols: [], // No external protocols
    },
  },
});

`refResolution` Options Reference

Option	Type	Default	Description
`allowedProtocols`	`string[]`	`['http', 'https']`	Protocols allowed for external `$ref` resolution. Supports any protocol (http, https, ftp, ws, wss, etc.). Set to `[]` to block all external refs.
`allowedHosts`	`string[]`	`undefined`	When set, only `$ref` URLs pointing to these hostnames are resolved. All other hosts are blocked.
`blockedHosts`	`string[]`	`undefined`	Additional hostnames/IPs to block, on top of the built-in internal IP block list.
`allowInternalIPs`	`boolean`	`false`	Set to `true` to disable the built-in internal/private IP block list. Warning: may expose to SSRF.

Polling & Live Updates

The adapter can automatically detect changes to your OpenAPI spec and rebuild tools at runtime — no server restart required.

OpenapiAdapter.init({
  name: 'my-api',
  baseUrl: 'https://api.example.com',
  url: 'https://api.example.com/openapi.json',
  polling: {
    enabled: true,
    intervalMs: 60000, // Poll every minute
  },
});

When a spec change is detected (via content hash, ETag, or auto strategy), the adapter:

Resets its internal generator
Calls fetch() to regenerate all tools
Notifies subscribers via onUpdate()

Subscribe to updates for logging, metrics, or downstream notifications:

const adapter = OpenapiAdapter.init({
  name: 'my-api',
  baseUrl: 'https://api.example.com',
  url: 'https://api.example.com/openapi.json',
  polling: { enabled: true, intervalMs: 60000 },
});

adapter.onUpdate((response) => {
  console.log(`Tools rebuilt: ${response.tools?.length} tools`);
});
adapter.startPolling();

For complete configuration options (retry, health monitoring, change detection strategies, and best practices), see the Polling & Live Updates guide.

How It Works

Request Processing

Path Parameters — Interpolated into URL template (e.g., /users/{id} → /users/123)
Query Parameters — Validated and appended to URL
Headers — Merged from additionalHeaders, headersMapper, and security config
Request Body — Validated and transformed by bodyMapper (for POST/PUT/PATCH)
Authentication — Applied via selected strategy (auth provider mapper, security resolver, etc.)

Response Processing

JSON responses — Automatically parsed to objects
Text responses — Returned as plain text
Error responses — Thrown as errors with status code and message

Complete Examples

Multi-Provider OAuth Application

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

@App({
  id: 'multi-provider-app',
  name: 'Multi-Provider Integration',
  adapters: [
    // GitHub API
    OpenapiAdapter.init({
      name: 'github',
      url: 'https://api.github.com/openapi.json',
      baseUrl: 'https://api.github.com',
      authProviderMapper: {
        GitHubAuth: (ctx) => ctx.authInfo.user?.githubToken,
      },
    }),

    // Slack API
    OpenapiAdapter.init({
      name: 'slack',
      url: 'https://api.slack.com/openapi.json',
      baseUrl: 'https://api.slack.com',
      authProviderMapper: {
        SlackAuth: (ctx) => ctx.authInfo.user?.slackToken,
      },
    }),
  ],
})
export default class MultiProviderApp {}

Multi-Tenant SaaS Application

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

@App({
  id: 'saas-app',
  name: 'SaaS Platform',
  adapters: [
    OpenapiAdapter.init({
      name: 'backend:api',
      spec: require('./openapi.json'),
      baseUrl: process.env.API_BASE_URL!,
      headersMapper: (ctx, headers) => {
        // Add tenant ID to all requests
        if (ctx.authInfo?.user?.tenantId) {
          headers.set('x-tenant-id', ctx.authInfo.user.tenantId);
        }

        // Add user authorization
        if (ctx.authInfo?.token) {
          headers.set('authorization', `Bearer ${ctx.authInfo.token}`);
        }

        return headers;
      },
      bodyMapper: (ctx, body) => {
        // Add user context to all mutations
        return {
          ...body,
          tenantId: ctx.authInfo?.user?.tenantId,
          userId: ctx.authInfo?.user?.id,
          timestamp: new Date().toISOString(),
        };
      },
    }),
  ],
})
export default class SaasApp {}

Expense Management (From Demo)

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

@App({
  id: 'expense',
  name: 'Expense MCP app',
  adapters: [
    OpenapiAdapter.init({
      name: 'backend:api',
      url: process.env.OPENAPI_SPEC_URL!,
      baseUrl: process.env.API_BASE_URL!,
      headersMapper: (ctx, headers) => {
        const token = ctx.authInfo?.token;
        if (token) {
          headers.set('authorization', `Bearer ${token}`);
        }
        return headers;
      },
    }),
  ],
})
export default class ExpenseMcpApp {}

Security Best Practices

Use Auth Provider Mapper

For multi-provider authentication, use authProviderMapper to map each security scheme to the correct auth provider. This provides LOW security risk.

Never Hardcode Credentials

Always store credentials in environment variables or secrets manager. Never commit credentials to source control.

Avoid includeSecurityInInput

Setting generateOptions.includeSecurityInInput: true exposes auth fields to MCP clients (HIGH risk). Only use for development/testing.

Validate User Context

Always validate that authInfo.user contains the expected fields before extracting tokens. Handle missing tokens gracefully.

Security Risk Levels

The adapter automatically validates your security configuration and assigns a risk score:

Risk Level	Configuration	Description
LOW ✅	`authProviderMapper` or `securityResolver`	Auth resolved from user context, not exposed to clients
MEDIUM ⚠️	`staticAuth`, `additionalHeaders`, or default	Static credentials or default behavior
HIGH 🚨	`generateOptions.includeSecurityInInput: true`	Auth fields exposed to MCP clients (not recommended)

Built-in Security Protections

Beyond authentication, the adapter includes defense-in-depth protections:

Protection	Description
$ref SSRF Prevention	Blocks `file://` protocol and internal/private IPs during `$ref` dereferencing. Configurable via `refResolution`.
SSRF Prevention	Validates server URLs, blocks dangerous protocols (`file://`, `javascript://`, `data:`)
Header Injection	Rejects control characters (`\r`, `\n`, `\x00`, `\f`, `\v`) in header values
Prototype Pollution	Blocks reserved JS keys (`__proto__`, `constructor`, `prototype`) in input transforms
Request Size Limits	Content-Length validation with integer overflow protection
Query Param Collision	Detects conflicts between security and user input parameters

Auth Type Routing: Tokens are automatically routed to the correct context field based on security scheme type (Bearer → jwt, API Key → apiKey, Basic → basic, OAuth2 → oauth2Token).

These protections are automatic—no configuration required. See the README for implementation details.

Troubleshooting

Error: Missing auth provider mappings

Cause: Your OpenAPI spec defines security schemes that aren’t mapped in authProviderMapper.Solution: Add all required security schemes to authProviderMapper:

authProviderMapper: {
  'GitHubAuth': (ctx) => ctx.authInfo.user?.githubToken,
  'SlackAuth': (ctx) => ctx.authInfo.user?.slackToken,
  // Add all security schemes from your spec
}

Error: Authentication required but no auth configuration found

Cause: The tool requires authentication but no auth configuration was provided.Solution: Choose one of the authentication strategies:

Add authProviderMapper (recommended for multi-provider)
Add securityResolver (for custom logic)
Add staticAuth (for server-to-server)
Add additionalHeaders (for static API keys)

Tools not appearing

Cause: Tools may be filtered out by filterFn or excludeOperations.Solution: Check your filter configuration or remove filters to include all operations.

Request fails with 401 Unauthorized

Cause: Authentication token is missing or invalid.Solution:

Verify authInfo.user contains the expected token fields
Check that token extraction returns a valid value
Verify the token is not expired
Check API logs for specific auth errors

TypeScript errors with OpenAPI spec

Cause: OpenAPI spec may not be typed correctly.Solution: Cast the spec to OpenAPIV3.Document:

import { OpenAPIV3 } from 'openapi-types';

const spec = require('./openapi.json') as OpenAPIV3.Document;

API Reference

OpenapiAdapter.init(options)

Creates a new OpenAPI adapter instance. Parameters:

options: OpenApiAdapterOptions — Adapter configuration

Returns: Adapter instance ready for use in @App({ adapters: [...] })

Security Types

// Security context passed to mcp-from-openapi
interface SecurityContext {
  jwt?: string;
  apiKey?: string;
  basic?: { username: string; password: string };
  oauth2Token?: string;
  apiKeys?: Record<string, string>;
  customHeaders?: Record<string, string>;
}

// Auth info from FrontMCP
interface AuthInfo {
  token?: string;
  user?: {
    id?: string;
    email?: string;
    [key: string]: any; // Custom user fields
  };
}

Performance Tips

The adapter uses lazy loading — the OpenAPI spec is only loaded and tools are only generated on first use, not during initialization.

Combine with app-level plugins (caching, logging, metrics) to enhance all generated tools automatically.

Use filterFn to generate only the tools you need, reducing initialization time and memory usage.

Links & Resources

Demo Application

See the expense management demo app using the OpenAPI adapter

Example OpenAPI Spec

OpenAPI spec used in the demo application

Generator Library

Underlying library for OpenAPI to MCP conversion

Source Code

View the adapter source code

​Why use it

​Installation

​Quick start

​Configuration

​Required Options

​Optional Configuration

​Authentication

​Strategy 1: Static Headers (Medium Risk)

​Strategy 2: Auth Provider Mapper (Low Risk) ⭐ Recommended

​Strategy 3: Custom Security Resolver (Low Risk)

​Strategy 4: Static Auth (Medium Risk)

​Strategy 5: Dynamic Headers & Body Mapping (Low Risk)

​Default Behavior (Medium Risk)

​Advanced Features

​Filtering Operations

​Input Schema Transformation

​Input Schema Transforms

​Tool Transforms

​Output Schema Display

​Custom Schema Formatter

​Data Transforms

​Pre-Tool Transforms (Schema Level)

​Post-Tool Transforms (Response Level)

​x-frontmcp OpenAPI Extension

​Description Mode

​Format Resolution

​Load Options

​$ref Resolution Security

​refResolution Options Reference

​Polling & Live Updates

​How It Works

​Request Processing

​Response Processing

​Complete Examples

​Multi-Provider OAuth Application

​Multi-Tenant SaaS Application

​Expense Management (From Demo)

​Security Best Practices

Use Auth Provider Mapper

Never Hardcode Credentials

Avoid includeSecurityInInput

Validate User Context

​Security Risk Levels

​Built-in Security Protections

​Troubleshooting

​API Reference

​OpenapiAdapter.init(options)

​Security Types

​Performance Tips

​Links & Resources

Demo Application

Example OpenAPI Spec

Generator Library

Source Code

Why use it

Installation

Quick start

Configuration

Required Options

Optional Configuration

Authentication

Strategy 1: Static Headers (Medium Risk)

Strategy 2: Auth Provider Mapper (Low Risk) ⭐ Recommended

Strategy 3: Custom Security Resolver (Low Risk)

Strategy 4: Static Auth (Medium Risk)

Strategy 5: Dynamic Headers & Body Mapping (Low Risk)

Default Behavior (Medium Risk)

Advanced Features

Filtering Operations

Input Schema Transformation

Input Schema Transforms

Tool Transforms

Output Schema Display

Custom Schema Formatter

Data Transforms

Pre-Tool Transforms (Schema Level)

Post-Tool Transforms (Response Level)

x-frontmcp OpenAPI Extension

Description Mode

Format Resolution

Load Options

$ref Resolution Security

`refResolution` Options Reference

Polling & Live Updates

How It Works

Request Processing

Response Processing

Complete Examples

Multi-Provider OAuth Application

Multi-Tenant SaaS Application

Expense Management (From Demo)

Security Best Practices

Security Risk Levels

Built-in Security Protections

Troubleshooting

API Reference

OpenapiAdapter.init(options)

Security Types

Performance Tips

Links & Resources