What OpenAPI to MCP means
OpenAPI to MCP turns HTTP API operations into tools that MCP-compatible AI clients can discover and call.
The Gateway reads a Swagger/OpenAPI JSON or YAML document and creates draft MCP tool definitions from the operations in that document. Each selected operation can become a named tool with an input schema, description, and Gateway-routed execution path.
The useful part is not simply converting routes into tools. A REST API is written for developers and software clients. An MCP tool catalog is read by AI clients, so it needs smaller surfaces, clearer descriptions, safer defaults, and server-side controls around credentials, limits, logging, and upstream execution.
A good OpenAPI to MCP setup usually publishes fewer tools than the source API contains. The OpenAPI file remains the source of technical truth, but the MCP surface becomes the model-facing contract.
What changes when an API becomes an MCP surface
The upstream API does not need to become agent-aware. The Gateway creates the AI-facing layer in front of selected operations.
| API concept | MCP-facing equivalent | Why it matters |
|---|---|---|
| Route | Named tool | The model chooses from tool names and descriptions, not raw route lists. |
| Path, query, or body schema | Tool input schema | Arguments can be validated before the upstream API is called. |
| API documentation | Agent-ready description | Descriptions tell the model when to use the tool and what constraints apply. |
| API key or bearer token | Gateway-managed upstream credential | MCP clients authenticate to the Gateway without carrying broad upstream secrets. |
| API logs | Tool usage and redacted logs | Teams can inspect AI-driven traffic by tool, latency, success, failure, and quota pressure. |
Recommended publish flow
Treat generated tools as a draft catalog, then publish only the operations an AI workflow should use.
The fastest path is not always the safest path. Importing a large OpenAPI file and publishing everything creates a noisy tool catalog and can make the model choose operations that were never meant for autonomous use.
Start with one business workflow. For example, support triage might need search orders, get customer status, and create support ticket. It probably does not need delete user, refund payment, rotate token, or bulk update account settings.
- Import the OpenAPI source URL and confirm that operation names, schemas, and auth requirements are detected.
- Group operations by workflow instead of by controller or tag alone.
- Hide broad, destructive, internal, admin, token-management, bulk-update, and low-signal endpoints by default.
- Rewrite descriptions so each published tool says what it does, when to use it, which inputs matter, and what result it returns.
- Use Gateway Chat to ask realistic questions and verify whether the model chooses the intended tool.
- Only after the chat test is clean, connect external clients such as Claude, Cursor, VS Code, or an internal agent.
Writing agent-ready tool descriptions
Endpoint comments are often too short for model tool selection. Agent-ready descriptions are explicit and operational.
| Weak description | Better description | Reason |
|---|---|---|
| Gets orders. | Search approved orders by customer, status, or date range before support follow-up. Use limit to keep the result small. | The better version tells the model when to use the tool and which filters matter. |
| Creates ticket. | Create a support ticket after the user confirms the customer, issue summary, and priority. | The better version explains the confirmation condition for a write action. |
| Updates user. | Hidden until there is a reviewed workflow. | Some operations should not become tools just because they exist in OpenAPI. |
| Fetch customer. | Read customer status and account flags for a specific customer ID; do not use this for broad customer search. | The better version distinguishes lookup from search. |
Security model
MCP clients should not receive broad upstream API credentials.
In the recommended setup, clients authenticate to the Gateway. The Gateway applies integration state, account limits, tool publication state, upstream credential policy, and redacted logging before forwarding requests to the REST API.
This keeps the OpenAPI source useful for AI workflows without turning local client configuration or prompts into the security boundary.
For write operations, use extra caution. Publish them only when the workflow, required arguments, confirmation expectations, logging behavior, and upstream permission model are clear.
Example MCP tool contract from an OpenAPI operation
A good tool contract is smaller and clearer than the raw API surface.
The model sees a task-oriented tool and typed arguments. The upstream API can still be a normal REST endpoint behind the Gateway. The Gateway handles the server-side route, upstream credential policy, usage limits, and redacted logging.
Agent-ready tool example
json{
"name": "search_orders",
"description": "Search approved orders by customer, status, or date range before support follow-up. Use limit to keep the result small.",
"inputSchema": {
"type": "object",
"properties": {
"customerId": { "type": "string" },
"status": { "type": "string" },
"fromDate": { "type": "string", "format": "date" },
"limit": { "type": "integer", "maximum": 50 }
},
"required": ["status"]
}
}When this approach fits
OpenAPI to MCP works best when an organization already has useful REST APIs and needs a governed AI-facing tool layer.
| Use case | Why OpenAPI to MCP helps | First surface to publish |
|---|---|---|
| Internal operations APIs | Expose selected support, order, ticketing, or workflow operations without distributing broad API keys. | Read and lookup tools, then carefully reviewed write helpers. |
| Customer-facing SaaS APIs | Ship an MCP endpoint while keeping quota, plan, and tool-level governance in the Gateway. | The few workflows customers already ask support or docs about. |
| Developer demos | Turn public OpenAPI specs into working MCP surfaces for prototypes and agent evaluations. | A small set of predictable tools with clear example prompts. |
| Internal agent pilots | Test whether existing APIs are understandable to AI clients before committing to custom MCP server code. | One workflow with stable inputs and clear expected outputs. |
Common anti-patterns
Most OpenAPI to MCP failures come from publishing too much or explaining too little.
- Do not publish every endpoint in a large OpenAPI document as a first release.
- Do not assume developer-facing route documentation is enough for AI tool selection.
- Do not put upstream API keys into Claude, Cursor, VS Code, or local MCP config when the Gateway can hold them server-side.
- Do not expose destructive write operations without a narrow workflow and upstream permission model.
- Do not treat tool descriptions as enforcement. Descriptions are guidance; validation and authorization belong in backend code.
- Do not skip logs. If a tool is useful enough for an agent, it is important enough to monitor.
Common questions
Does every OpenAPI endpoint become a public MCP tool?
No. The Gateway can generate operation-derived tools, but the published MCP surface should be curated. Unsafe or unnecessary operations can be hidden.
What makes a tool description agent-ready?
An agent-ready description states what the tool does, when to use it, which inputs matter, and what constraints apply. Clear descriptions help MCP clients choose the correct operation.
Should write endpoints become MCP tools?
Only after review. Write operations should have clear descriptions, required arguments, upstream permissions, logging, and any confirmation requirements before they are published to AI clients.
Do MCP clients need the upstream API key?
No. Clients authenticate to the Gateway. Upstream credentials are handled server-side by the Gateway in the recommended flow.
How do I know if the catalog is too broad?
If a user question could match many similar tools, if admin routes appear next to normal workflow tools, or if the model chooses the wrong operation in Gateway Chat, the catalog is too broad.