OpenAPI to MCP: Complete Guide
If your API has an OpenAPI spec (also called a Swagger spec), converting it to an MCP server is straightforward. This guide walks through the process and explains what to watch out for. If you want a starting point after the concepts, browse Production MCP Server Templates.
What Is an OpenAPI Spec?
An OpenAPI spec is a machine-readable description of your REST API. It lists every endpoint, the parameters each one accepts, and the structure of responses. Most modern API frameworks generate one automatically.
Common locations:
https://your-api.com/openapi.jsonhttps://your-api.com/swagger.jsonhttps://your-api.com/docs
How OpenAPI Maps to MCP Tools
Each endpoint in your OpenAPI spec becomes one MCP tool:
| OpenAPI | MCP Tool |
|---|---|
operationId | Tool name |
summary or description | Tool description |
parameters + requestBody | Input schema |
responses | Return value |
What to Watch Out For
Tool Name Length
Claude Desktop has a 64-character limit on tool names. If your operationId values are long, they'll need to be truncated. MCPForge handles this automatically.
Missing Descriptions
Tools without descriptions are harder for AI agents to use correctly. The AI relies on descriptions to decide when to call each tool. Fill in summaries for every endpoint in your spec. If the generated MCP server will be consumed from a Vercel app, pair this workflow with the AI SDK MCP guide so discovered tools are passed into generateText() or streamText() correctly.
Dangerous Endpoints
Not all endpoints should be exposed to AI agents. Before connecting Claude to your API, review which endpoints could cause damage if called incorrectly:
- DELETE endpoints (irreversible data loss)
- Billing endpoints (financial impact)
- Auth endpoints (credential exposure)
- Admin endpoints (privilege escalation)
MCPForge automatically detects these using keyword analysis and disables them by default.
Authentication
Your API likely requires authentication. Never put API keys in the MCP client configuration — they'll be visible to anyone who can read the config file. Use a hosted MCP server that injects credentials server-side.
Converting with MCPForge
- Find your OpenAPI spec URL (e.g.,
https://api.yourservice.com/openapi.json) - Paste it into MCPForge
- Review the generated tools — high-risk endpoints are flagged automatically
- Enable or disable tools based on what Claude should access
- Add your API credentials in the Credentials Vault
- Copy the Claude Desktop config and paste it into
claude_desktop_config.json
Claude can now call your API through MCP, with full audit logging of every tool call.
Want to analyze your API security?
Import your OpenAPI spec and generate a Security Report automatically.
Official Sources
- OpenAPI Specification - authoritative reference for OpenAPI documents, paths, operations, parameters, request bodies, and schemas.
- MCP tools specification - explains how MCP tools are listed, described, and invoked.
- MCP TypeScript SDK - official SDK for building MCP servers and clients.