@avidian/mcp-openapi

MCP server for OpenAPI/Swagger. It lets an AI agent discover, inspect, and call any REST API described by an OpenAPI or Swagger document, while keeping the agent's context footprint small.

Instead of registering one MCP tool per API operation (which pushes every operation's schema into the agent's context up front), this server exposes a small, fixed set of generic meta-tools. The agent loads one or more specs at runtime, searches and inspects their operations on demand, and executes them - all through the same six tools, no matter how large or how many specs are loaded.

Installation

npm (requires Node.js >= 20)

npm install -g @avidian/mcp-openapi

Compiled binary (no runtime needed)

Download from GitHub Releases.

Related MCP server: Swagger/Postman MCP Server

How it works

The server holds an in-memory registry of loaded specs. Each loaded spec is a single OpenAPI/Swagger document (2.0, 3.0, or 3.1) together with its parsed operations, and is identified by a spec id - a lowercase ULID the server generates automatically. The agent discovers spec ids by listing what is loaded, then passes an id to the other tools. Nothing is persisted: a restart starts fresh and re-runs any startup preloads.

Meta-tools

The server registers exactly these six tools, and never one tool per operation:

Operations are referenced by their method and path (for example get and /pets/{petId}), exactly as search_operations reports them.

Usage

The server can start empty and let the agent load everything at runtime, or preload one or more specs at startup.

# Start empty; the agent calls load_spec at runtime.
mcp-openapi

# Preload a single spec (the common case).
mcp-openapi https://petstore3.swagger.io/api/v3/openapi.json
mcp-openapi ./openapi.yaml --base-url https://api.internal.example.com --timeout 10000

# Preload several specs, each with its own settings, from a config file.
mcp-openapi --config ./specs.json

CLI shape:

mcp-openapi [<source>] [--base-url <url>] [--credential <name>] [--timeout <ms>] [--config <path>]

The single positional <source> may also come from OPENAPI_URL, which is convenient for MCP client configs.

Config file

A JSON config file preloads any number of specs, each with an optional per-spec base URL and credential reference:

{
  "specs": [
    { "source": "https://api.example.com/openapi.json", "credential": "example" },
    { "source": "./internal.yaml", "base_url": "https://api.internal.example.com" }
  ],
  "max_specs": 20,
  "request_timeout_ms": 30000,
  "max_response_bytes": 100000
}

Unknown keys are rejected so typos surface. A preload that fails to load is logged to stderr and skipped; the server still starts, and the agent can load specs at runtime.

MCP client configuration

{
  "mcpServers": {
    "openapi": {
      "command": "mcp-openapi",
      "args": ["--config", "/path/to/specs.json"]
    }
  }
}

Configuration

Precedence for these knobs is: environment variable > config file > default. The request timeout additionally accepts the --timeout CLI flag, which wins over the environment variable; the response cap and max-specs knobs have no CLI flag.

Authentication

Credentials are always provisioned by the operator in the environment and resolved server-side; a secret value never passes through the agent.

The recommended approach is credential references. The operator provisions a secret under a reference name, and the agent (or config file) passes only that name to load_spec:

For example, provisioning OPENAPI_CRED_GITHUB_TOKEN and loading with credential: "github" applies that token to the spec's security scheme(s). A reference is applied only to the schemes named in the document's security requirement, so one secret is not sprayed across unrelated schemes. (When the document declares no top-level security, the reference is applied to every scheme it defines.)

When no credential is given, the server falls back to matching each of the document's security schemes by name (converted to SCREAMING_SNAKE_CASE):

Schemes with no matching environment variable are skipped silently; unsupported types (OAuth2, OpenID Connect) are skipped with a warning. Neither case fails startup.

Security note

load_spec fetches whatever URL or reads whatever local file the agent asks it to, and execute_operation calls the base URL declared by (or overridden for) a loaded spec, attaching the operator-provisioned credentials. This is intrinsic to the tool's purpose, but it means a spec pointing at an internal or metadata endpoint would be fetched and called from wherever the server runs. Run the server in an environment where that request surface is acceptable, and only provision credentials for APIs you intend the agent to call.

Development

# Install dependencies
bun install

# Run in dev mode
bun run dev [<source>]

# Type check
bun run typecheck

# Lint
bun run lint

# Format
bun run format

# Test
bun run test

# Everything the CI gate runs
bun run check

# Build for npm
bun run build

# Compile native binary
bun run compile

ajv is listed as a direct devDependency even though nothing in src/ imports it. It's a workaround: @apidevtools/swagger-parser depends on ajv-draft-04, which only declares ajv as a peer dependency, and Bun's bundler fails to statically resolve that peer dependency when producing standalone binaries (bun run compile) unless ajv is also resolvable as a direct dependency somewhere in the root of the tree. Not needed for bun run build (the npm-published bundle), which keeps @apidevtools/swagger-parser external and lets Node resolve it normally at install time.

License

MIT