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.
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.json`
- `https://your-api.com/swagger.json`
- `https://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.
Want to analyze your API security?
Import your OpenAPI spec and generate a Security Report automatically.
Generate Security Report →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.
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
1. Find your OpenAPI spec URL (e.g., `https://api.yourservice.com/openapi.json`)
2. Paste it into MCPForge
3. Review the generated tools — high-risk endpoints are flagged automatically
4. Enable or disable tools based on what Claude should access
5. Add your API credentials in the Credentials Vault
6. 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.