<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: imran shaikh</title>
    <description>The latest articles on DEV Community by imran shaikh (@imran_shaikh_1150c6972749).</description>
    <link>https://dev.to/imran_shaikh_1150c6972749</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4254155%2F6743324c-3728-4374-8ad9-39fdb03625db.png</url>
      <title>DEV Community: imran shaikh</title>
      <link>https://dev.to/imran_shaikh_1150c6972749</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/imran_shaikh_1150c6972749"/>
    <language>en</language>
    <item>
      <title>How to Turn an OpenAPI Spec Into an MCP Server (Without Giving Agents Every Endpoint)</title>
      <dc:creator>imran shaikh</dc:creator>
      <pubDate>Thu, 19 Nov 2026 16:04:30 +0000</pubDate>
      <link>https://dev.to/imran_shaikh_1150c6972749/how-to-turn-an-openapi-spec-into-an-mcp-server-without-giving-agents-every-endpoint-1f3h</link>
      <guid>https://dev.to/imran_shaikh_1150c6972749/how-to-turn-an-openapi-spec-into-an-mcp-server-without-giving-agents-every-endpoint-1f3h</guid>
      <description>&lt;p&gt;If your product has an API, AI agents can now use it for your users. Claude, ChatGPT, Cursor and VS Code all support MCP, so a customer could ask their assistant to check an order or book a slot in your product, and the assistant would do it.&lt;/p&gt;

&lt;p&gt;The catch is that an agent doesn't talk to your REST API directly. It talks to an MCP server. So the question a lot of API teams are asking is how to create an MCP server for their API, ideally from the OpenAPI spec they already have. I built a product for exactly this, and this post is what I learned about doing it well, whichever way you build it.&lt;/p&gt;

&lt;h2&gt;
  
  
  What an MCP server actually is
&lt;/h2&gt;

&lt;p&gt;MCP, the Model Context Protocol, is an open-source standard for connecting AI applications to external systems. The official docs compare it to a USB-C port for AI applications: one standard way to plug things in.&lt;/p&gt;

&lt;p&gt;An MCP server exposes tools. Each tool has a name, a description, and a JSON Schema for its inputs. The client asks the server for its list of tools, the model picks one based on what the user asked, and the client calls it. For a remote server, the standard transport is Streamable HTTP: one endpoint, such as &lt;a href="https://example.com/mcp" rel="noopener noreferrer"&gt;https://example.com/mcp&lt;/a&gt;, that clients send their messages to.&lt;/p&gt;

&lt;p&gt;So converting a REST API to an MCP server means deciding which tools to expose, describing them well, and running a server that turns each tool call into the right API requests.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why a one-to-one endpoint-to-tool conversion works badly
&lt;/h2&gt;

&lt;p&gt;The obvious approach is to turn every operation in your OpenAPI spec into a tool. It works in a demo. In practice it causes four problems.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Too many tools. A real API can have dozens or hundreds of operations. The model has to choose between all of them on every request, and similar-looking endpoints are easy to confuse.&lt;/li&gt;
&lt;li&gt;Endpoints that should never be there. Health checks, internal admin routes and reindex jobs are in the spec, but no agent should ever call them.&lt;/li&gt;
&lt;li&gt;Descriptions written for developers. An OpenAPI summary like "Get resource by ID" tells a model almost nothing about when to use it.&lt;/li&gt;
&lt;li&gt;No guardrails on changes. A DELETE endpoint becomes a tool just like a GET, with nothing that says it can't be undone.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  How to convert an OpenAPI spec to an MCP server properly
&lt;/h2&gt;

&lt;p&gt;These steps apply whether you write the server by hand with an MCP SDK or use a tool.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;&lt;p&gt;Pick the endpoints. Start from what a user would ask an agent to do, not from the spec. Leave out internal, health and admin routes entirely.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Group them into a few task-shaped tools. An agent thinks in tasks like "find an open slot" or "book it", not in routes. One tool can call two endpoints if that's what the task needs. Fewer, clearer tools are easier for a model to choose between.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Write descriptions for the model. Say what the tool does, when to use it, and what each parameter means. Hide parameters the agent should never set. If a tool changes data, say so in the description and tell the agent to confirm with the user first.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Mark what each tool can do. The MCP spec has optional annotations for this, such as readOnlyHint and destructiveHint. Treat them as hints, not security: the spec says clients should consider annotations untrusted unless they come from a trusted server, so the real protection is which tools you expose at all.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Keep human confirmation for changes. The MCP spec says there should always be a human in the loop with the ability to deny tool invocations. Your descriptions and labels help clients ask before a write or a delete.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Keep your API credentials out of the AI client. The agent should never see the key your server uses to call your API. Store it on the server side, encrypted, and use it only when a call is made.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Add auth, keys and rate limits on the MCP side. The spec says servers must validate tool inputs, implement access controls and rate limit tool invocations. Issue a separate key per team or agent so you can revoke one without breaking the others.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Test with a real client. Connect the server to an actual assistant and try the questions your users would ask. Look at every call, its arguments and its response. Bad descriptions show up fast.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Host it as a remote server. A local server only works on one machine. A hosted endpoint over Streamable HTTP is something your customers can paste into their own AI client.&lt;/p&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Doing it with MCPEasy
&lt;/h2&gt;

&lt;p&gt;I built MCPEasy because steps 6 to 9 are the same work for every API, and teams should only have to decide steps 1 to 5. Here's what it does today:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Import an OpenAPI URL, upload a spec file or drop in a Postman collection. Nothing to install.&lt;/li&gt;
&lt;li&gt;It groups your endpoints into a small set of clear tools and writes descriptions agents understand. Internal and health endpoints are skipped automatically.&lt;/li&gt;
&lt;li&gt;You can rename tools, rewrite descriptions and hide parameters.&lt;/li&gt;
&lt;li&gt;Every tool is labelled read only, write or destructive, and you can switch any tool off.&lt;/li&gt;
&lt;li&gt;You test the tools in a playground and see every call, argument and response before going live.&lt;/li&gt;
&lt;li&gt;You get a hosted MCP endpoint with API keys and rate limits, ready to paste into any client that supports remote MCP servers, including Claude, ChatGPT, Cursor, VS Code and custom agents built with an MCP SDK.&lt;/li&gt;
&lt;li&gt;Secrets for your API are encrypted at rest and only decrypted inside the gateway when a call is made. They are never sent to the AI client.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;It's fully hosted, so there's no self-hosted option yet. You need an existing HTTP API described by an OpenAPI spec or a Postman collection. It's free to start: &lt;a href="https://mcpeasy.net" rel="noopener noreferrer"&gt;https://mcpeasy.net&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Questions
&lt;/h2&gt;

&lt;p&gt;Do I need an OpenAPI spec to create an MCP server for my API? Not if you write the server by hand with an MCP SDK. But a spec or a Postman collection makes generating one much faster, because the endpoints, parameters and types are already described.&lt;/p&gt;

&lt;p&gt;Can I just expose every endpoint as a tool? You can, but the agent will struggle to choose between them, and internal or destructive endpoints become callable. A few task-shaped tools work better.&lt;/p&gt;

&lt;p&gt;Are MCP tool annotations enough to stop an agent deleting data? No. The spec treats annotations as hints and tells clients not to trust them from untrusted servers. Leave out tools you don't want called, and keep human confirmation for changes.&lt;/p&gt;

&lt;p&gt;Which AI clients can connect to a remote MCP server? Any client that supports remote MCP servers. The official docs list Claude, ChatGPT, Visual Studio Code and Cursor among the many that support MCP.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published on &lt;a href="https://medium.com/@imranshaikh052002/how-to-turn-an-openapi-spec-into-an-mcp-server-without-giving-agents-every-endpoint-60e07aa1592b" rel="noopener noreferrer"&gt;Medium&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>mcp</category>
      <category>ai</category>
      <category>api</category>
      <category>openapi</category>
    </item>
  </channel>
</rss>
