OpenAPI

You can turn an OpenAPI specification into a dynamic MCP (Model Context Protocol) server that exposes your API as AI-accessible tools. This lets AI assistants interact with your REST API through a structured, discoverable set of actions, while preserving API security and metadata details.

How to use

Configure your MCP client to connect to the local or remote MCP server you set up from an OpenAPI spec. You will run an MCP server that loads the OpenAPI document (and optional overlays), maps operations to tools, and then exposes those tools to an AI agent. Your client can then request available tools, query API operations, and execute actions through the MCP interface.

Typical usage pattern: start the MCP server with your OpenAPI spec, then connect an AI assistant client to fetch the available tools and invoke them as needed. If you provide overlays or filters, the server will limit the exposed operations accordingly and keep your API calls aligned with the defined security and header configurations.

In practice, you interact with the MCP server by configuring your MCP client to reference the server, then issuing prompts that reference the exposed tools. The server handles translation between AI prompts and API calls, including parameter handling, authentication, and headers.

How to install

Prerequisites: you need Node.js installed on your machine.

Install and run the MCP server by using an inline command pattern shown in the examples. The server is typically invoked via a package runner such as npm/npx, pointing to the MCP tool package and the OpenAPI spec.

Example starting point to run an MCP server with an OpenAPI spec hosted online:

{
  "mcpServers": {
    "api_tools": {
      "command": "npx",
      "args": [
        "-y",
        "@tyktechnologies/api-to-mcp",
        "--spec",
        "https://petstore3.swagger.io/api/v3/openapi.json"
      ],
      "enabled": true
    }
  }
}

Configuration and notes

Configuration can be provided via environment variables, command-line options, or a JSON configuration file. You can specify the OpenAPI spec location, overlays, whitelist/blacklist patterns, target API base URL, and custom headers. The server uses the OpenAPI metadata for description and capabilities, and supports X-MCP tracking headers for request identification.

Environment variables commonly used include OPENAPI_SPEC_PATH, OPENAPI_OVERLAY_PATHS, TARGET_API_BASE_URL, MCP_WHITELIST_OPERATIONS, MCP_BLACKLIST_OPERATIONS, API_KEY, SECURITY_SCHEME_NAME, SECURITY_CREDENTIALS, CUSTOM_HEADERS, HEADER_* variants, and DISABLE_X_MCP. You can also provide a JSON configuration file with equivalent fields.

Security and customization notes

The MCP server supports authentication handling for your target API and can apply custom headers to all requests. It also supports OpenAPI overlays to modify or extend the base specification without altering the original file.

You can disable the X-MCP header if needed. When you set up tools, you can leverage path-level x-mcp extensions to override tool names and descriptions, enabling branded and clearer tool presentation.

Available tools

load_openapi

Load an OpenAPI specification from a file or URL and parse the API structure to prepare tools.

load_overlays

Optionally load OpenAPI overlays from local files or URLs to modify the base spec before tool generation.

map_operations

Customize how OpenAPI operations are mapped to MCP tools, including naming and descriptions.

filter_operations

Apply glob pattern filters to limit exposed operations by operationId or URL path.

handle_parameters

Preserve parameter formats and capture location metadata to ensure accurate API calls.

authenticate_api

Configure API authentication handling for requests to the target API.

set_http_headers

Configure custom HTTP headers that are sent with every API request via environment or config.

x_mcp_tracking

Include X-MCP header for tracking and identification of API requests.

x_mcp_overrides

Support custom x-mcp extensions at the path level to override tool names and descriptions.