The mapping: operation → tool
Converting REST to MCP is a disciplined translation, not an invention:
- Tool name ←
operationId(or method+path when missing). - Input schema ← path/query/header parameters +
requestBody, merged into one JSON schema. - Execution ← rebuild the HTTP call: substitute path params, encode query arrays, set the body content type, attach auth.
- Description ← the operation summary — as a starting point only (more below).
A practical conversion checklist
- Validate the spec first. Most real-world OpenAPI files have drifted from the API. A scan that probes a few harmless GETs catches dead endpoints before your customers' agents do.
- Curate the tool list. Expose what a customer would ask for in plain words; hide admin and bulk endpoints. Fewer, better-described tools beat coverage.
- Mark reads vs writes. Agents (and their users) need to know which calls change state. Derive it from the HTTP method and label it explicitly.
- Rewrite descriptions for agents. Concrete return shapes, enum values verbatim, ID provenance ("obtain from
list_projects.id"), date formats with examples. - Decide identity before launch. A shared key demo is fine; customers need their own credentials — per-customer keys or OAuth — with limits and revocation.
Gotchas that survive spec review
- Huge inputs. Deeply-nested request bodies overflow what an agent can fill reliably; flatten or split the tool.
- Pagination. Document what page 1 means and where the next cursor lives, or agents will loop.
- Server URLs. Specs often list staging servers first; pin the base URL explicitly.
- Auth mismatch. The spec says
bearer, the API expects a custom header — probe, don't trust.
Or paste the spec and skip the checklist
Command+K's wizard runs this whole pipeline — scan, curation UI, read/write flags, AI-written agent descriptions — and publishes a hosted MCP with per-customer auth, logs and quotas. A real 84-tool API went spec-to-live in one afternoon.
FAQ
- How do I convert an OpenAPI spec to an MCP server?
- Map each OpenAPI operation to one MCP tool: operationId becomes the tool name, parameters and requestBody become the JSON-schema input, and the description becomes the tool doc. Then wrap execution so the tool call becomes the right HTTP request (path/query/header params, body encoding, auth header). Hosted converters like Command+K do this from a pasted spec or URL and publish the result on a stable MCP endpoint.
- Should I expose every endpoint of my API as an MCP tool?
- No. Agents pick tools by reading descriptions; 300 tools make picking worse, not better. Curate: expose the 20-80 operations a customer would actually ask for in words, mark writes clearly, and leave admin/internal endpoints out.
- What makes a good MCP tool description for OpenAPI-derived tools?
- Write for the agent, not the developer: what the tool returns (concrete field names), when to pick it over sibling tools, exact argument formats with examples, every enum value, and where IDs come from. Auto-generated one-liners from the spec are rarely enough.