Guide · May 20, 2026

OpenAPI to MCP: convert your API in 5 minutes

This guide walks through converting an OpenAPI 3.x specification into a hosted Model Context Protocol (MCP) server. By the end, your API will be callable from Claude, ChatGPT, Cursor, or any other MCP client. No code, no infrastructure, no SDKs.

Start the walkthrough See the sample spec

What does “OpenAPI to MCP” mean?

OpenAPI (formerly Swagger) is the most widely used format for describing REST APIs. If you’ve ever generated SDKs, built a developer portal, or seen interactive API docs at /docs, you’ve seen OpenAPI in action.

MCP (Model Context Protocol) is an open standard published by Anthropic for connecting AI assistants to external tools and data. An MCP server exposes a list of tools that AI clients (Claude, ChatGPT, Cursor, VS Code, and others) can call in response to user prompts.

OpenAPI to MCP means programmatically generating an MCP server from an OpenAPI spec, so each REST operation becomes a callable AI tool. You already wrote the OpenAPI spec; this just exposes it in a second protocol that AI assistants understand.

What you need before starting

An OpenAPI 3.x spec. Public URL or local file. JSON and YAML both supported. If you only have OpenAPI 2 (Swagger), convert with swagger2openapi first.
A Vayro account. Sign up free with Google. Free tier covers 1 project, 5,000 requests/month.
An MCP-compatible AI client if you want to test end to end. Claude CLI, ChatGPT, Cursor, Windsurf, and VS Code all work.

No spec handy? Use our worked example below, which references the Atlas Bookings sample spec (a fictional B2B booking API, 12 operations).

Step 1 of 5

Get your OpenAPI spec URL

Vayro accepts either a public URL or a pasted spec. For this walkthrough we’ll use the Atlas Bookings sample:

https://vayro.ai/openapi/sample.json

If your spec lives behind authentication, you can paste the raw JSON or YAML content instead. Vayro stores a versioned copy so the connection survives upstream changes.

Step 2 of 5

Paste the spec into Vayro

From your dashboard, click New project, give it a name, and paste the spec URL. Vayro fetches it, validates it, and generates one MCP tool per OpenAPI operation. For the Atlas Bookings sample, that’s 12 tools (list appointments, create appointment, get customer, and so on).

Each tool gets a name (from the OpenAPI operationId), a description (from the operation summary plus an AI-enhanced overlay), and a JSON schema (from the operation’s parameters and request body).

Step 3 of 5

Configure authentication

Most APIs need credentials. Open the API Auth tab and pick the scheme from your spec’s securitySchemes section:

Bearer token: paste the token, Vayro injects it as Authorization: Bearer ... on every upstream call.
API key: header or query parameter, whichever your spec declares.
OAuth 2.0: Vayro acts as the OAuth client, handling PKCE, refresh tokens, and per-user authorization codes.
Basic auth: username and password, base64-encoded by Vayro at request time.

All credentials are encrypted at rest with envelope encryption. Vayro never logs the decrypted values.

Step 4 of 5

Resolve OpenAPI server variables

Many multi-tenant SaaS APIs use templated server hosts like:

servers: - url: https://{tenant}.api.atlas-bookings.app variables: tenant: default: sandbox

In the Server Variables panel, supply the concrete value for each variable (your subdomain, region, API version, etc.). Vayro substitutes these at request time, so changing the value later is instant; no spec re-fetch required.

If you skip this step, requests will hit the literal placeholder host and fail.

Step 5 of 5

Connect from an AI client

Vayro gives you a hosted URL like:

https://mcp.vayro.ai/mcp/your-project-slug

Paste it into your MCP client of choice:

Claude CLI: claude mcp add --transport http your-project https://mcp.vayro.ai/mcp/your-project-slug, then run /mcp inside Claude to verify the connection.
ChatGPT: Settings → Apps & Connectors → Add MCP Server, paste the URL.
Cursor: add the URL to ~/.cursor/mcp.json.
VS Code (Continue): configure as a remote MCP server in your Continue settings.

That’s it. Your AI assistant now has access to every operation your OpenAPI spec describes. Ask it to “list my open appointments” or “book a haircut tomorrow at 3pm” and it will call the right tool.

What happens under the hood

The OpenAPI to MCP conversion is more than a syntactic translation. A few things matter:

Tool naming and grouping: Each operation becomes a tool. Names come from operationId. If yours are missing or unhelpful (getEndpoint1), Vayro can auto-rewrite them.
Tool descriptions: The AI tool-call decision relies heavily on the description string. Vayro applies an AI-written overlay on top of your OpenAPI summaries so the assistant picks the right tool the first time.
JSON Schema translation: OpenAPI parameter schemas become MCP input schemas. Nested request bodies are flattened where it improves model comprehension.
Protocol: Vayro speaks MCP’s streamable HTTP transport (2025-11-25 spec). It handles initialize, tools/list, tools/call, and the full lifecycle. The runtime is a Cloudflare Worker; cold start is under 50ms.
Per-request proxying: When the AI calls a tool, Vayro proxies to your upstream API, applies auth headers, substitutes server variables, and returns the response. No data is cached.

Common gotchas

Spec uses Swagger 2 instead of OpenAPI 3. Vayro only supports 3.x. Convert with npx swagger2openapi.
Server variables not configured. Requests will go to the literal {tenant}.api.example.com host and fail. Set values in the Server Variables panel.
Auth scheme missing from spec. If your spec lacks securitySchemes, Vayro can’t infer the right header. Add it to the spec or override in the API Auth tab.
Very large specs (500+ operations). MCP clients can struggle with huge tool lists. Use Vayro’s endpoint selection to expose only the operations the AI actually needs.
Upstream API is behind a private network. Vayro’s runtime is public; it can’t reach private hosts. For internal APIs, either expose them via a public ingress or contact us about self-hosted Vayro.

Frequently asked questions

What is MCP?+

Model Context Protocol is an open standard from Anthropic for connecting AI assistants to external tools and data. An MCP server exposes a set of tools that AI clients like Claude, ChatGPT, and Cursor can invoke.

Why convert OpenAPI to MCP?+

OpenAPI describes REST APIs in a machine-readable format. MCP is the protocol AI assistants speak. Converting OpenAPI to MCP lets you expose an existing API to AI agents without writing per-tool integration code.

Do I need to host the MCP server myself?+

No. Vayro hosts the MCP server for you. You get a URL like https://mcp.vayro.ai/mcp/your-project, and any MCP-compatible AI client can connect to it.

Does it work with OpenAPI 2 (Swagger)?+

Vayro supports OpenAPI 3.0 and 3.1 only. Convert older Swagger 2 specs with swagger2openapi first.

How does upstream authentication work?+

Vayro supports Bearer tokens, API keys (header or query), basic auth, and OAuth 2.0 (including per-user OAuth where each end user authenticates against your upstream).

Is the free tier really free?+

Yes. 1 project, 5,000 requests per month, no credit card. Paid tiers start at $49/mo for 5 projects and 100,000 requests.

What if my OpenAPI spec changes?+

Click re-fetch in the dashboard. Vayro pulls the new version, diffs it against the previous, and updates the generated MCP tools. Spec versions are kept so you can roll back.

Convert your OpenAPI spec now

Free tier covers 1 project and 5,000 requests per month. No credit card. Sign in with Google and you’ll have a hosted MCP server in under 5 minutes.

Start free Compare Vayro vs alternatives