How do I convert an OpenAPI spec to MCP?

Import the OpenAPI 3.x document (JSON or YAML, file or URL) into an MCP gateway like the open-source PlugMCP. Each operation becomes an MCP tool with a parameter schema, description and read/write classification — no code generation, no SDK, no custom server.

What about APIs with hundreds of endpoints — won't that flood the context window?

A good gateway prevents tool overload. PlugMCP switches to a compact search surface (search_tools, describe_tool, call_tool) past a configurable threshold, keeps curated recommended tools natively visible, and caps oversized responses with actionable hints.

Yes — OAuth2 client-credentials with token caching and early refresh, plus bearer, basic, header and query-parameter API keys, and static headers. Credentials are stored AES-256-GCM encrypted and injected server-side; the agent never sees them.

Is there a catalog of ready connectors?

PlugMCP ships 417 ready-made connectors generated from public API specifications — GitHub, Stripe, Slack-style SaaS and hundreds more — each verified to import into working tools.

PlugMCP / Guides / OpenAPI to MCP

OpenAPI to MCP: Turn Any REST API into Agent-Ready Tools

Updated July 2026 · one upload, no code · works with Claude, ChatGPT, Cursor, Copilot & any MCP client

Your company already documented its APIs — every OpenAPI/Swagger spec is a complete, machine-readable description of what an AI agent could do. The missing piece is the translation to Model Context Protocol, plus the governance you'd want before an agent starts calling production endpoints.

The short answer: import the OpenAPI 3.x document (JSON or YAML, file or URL) into the open-source PlugMCP gateway. Every operation becomes an MCP tool with a parameter schema, injected auth and a read/write classification. No code generation, no SDK, no server to write.

Why not just generate an MCP server from the spec?

Code generators exist, but they produce one more service to build, deploy and patch — per API. A gateway approach differs in three ways:

Zero code: importing a spec is a configuration change, not a deployment. Update the spec, re-import, done.
Shared governance: auth injection, scoped API keys, human approvals for writes, rate limits and the audit log apply to all your APIs at one choke point — instead of being re-implemented (or forgotten) per generated server.
Context-window protection: a 300-operation spec would flood an agent with 300 schemas. PlugMCP flips to a compact search surface (search_tools / describe_tool / call_tool) past a threshold, keeps curated tools natively visible and caps oversized responses with hints. Generated servers dump everything.

Step 1 — Import the spec

# run the gateway (single binary or Docker)
docker run -d -p 8080:8080 -v plugmcp:/data ghcr.io/plugmcp/plugmcp

Admin UI → Connectors → Add → OpenAPI → upload the file or paste the spec URL. The importer handles JSON and YAML, resolves $ref, allOf and oneOf, strips HTML from vendor descriptions, and synthesizes a description when the spec has none — so the resulting tools read cleanly to a model.

✓ imported petstore: 19 operations → 19 tools (14 read, 5 write)

Step 2 — Configure auth once

Set it on the connector; the gateway injects it on every call, server-side. The agent never sees a credential.

Scheme	Typical API
Bearer token	GitHub, Stripe, most SaaS
Header / query API key	legacy REST, internal services
Basic auth	Jira, older enterprise APIs
OAuth2 client-credentials	Microsoft Graph, enterprise IdPs — token cached & auto-refreshed

Credentials are stored AES-256-GCM encrypted; an SSRF guard blocks connectors from reaching internal networks unless explicitly allowed.

Step 3 — Connect the agent

Mint a scoped API key (this connector only, read-only if you like) and add the endpoint to your client:

claude mcp add --transport http plugmcp https://your-gateway/mcp \
  --header "Authorization: Bearer pmcp_…"

Claude Desktop, claude.ai, Cursor, ChatGPT and Copilot connect the same way — PlugMCP speaks standard MCP over streamable HTTP.

Or skip the spec: 417 ready connectors

For public SaaS APIs you often don't need to hunt for a spec at all. PlugMCP ships a catalog of 417 connectors generated from public API specifications, each one quality-gated (it must import into working tools) — GitHub, Stripe, Trello, Mailchimp, Telegram and hundreds more. One click, add your credential, done.

Write safety: operations classified as writes (POST/PUT/PATCH/DELETE) can be excluded per key, and with approvals enabled each write waits for a human click in the UI before it executes — with a full audit trail either way.

FAQ

Which OpenAPI versions are supported?

OpenAPI 3.x in JSON or YAML. Swagger 2.0 documents can be converted with the standard swagger2openapi tool first.

What happens with huge specs?

They import fine — and agents don't drown, because past a configurable threshold the gateway exposes search-based tool discovery instead of hundreds of schemas.

Can I edit tool descriptions?

Yes — descriptions, recommended flags and read-only classification are editable per tool, and overlay files let you version-control those improvements.

What does it cost?

Nothing. 100% AGPL-3.0 open source, self-hosted, no license keys, no phone-home. Commercial licenses exist for OEM embedding.

Your APIs are already documented. Make them agent-ready.
Get PlugMCP on GitHub Learn more