What API2MCP Does, and Seven Ways to Put It to Work

A tour of what API2MCP actually does to a REST API, from import to a running MCP server, followed by seven concrete ways people use it with Claude, Cursor, and other MCP clients.

Most of the posts on this blog go deep on one piece: how discovery turns an operation into a tool, how the two auth layers work, why 180 tools is too many. This one is the map. It covers everything the platform does to an API between "here's my spec" and "Claude just called it," and then it gets practical about what people actually point it at.

If you want the one-line version: API2MCP takes a REST API you already have and gives you a hosted MCP server for it, without you writing or deploying server code. Your credentials stay on that server. The model gets tools, and nothing else.

Getting an API in

Everything starts with a provider, which is the platform's word for an upstream API. A provider has a base URL, an auth scheme, and a description of its endpoints. There are several ways to supply that last part, and you'll use whichever your API makes easy.

The easy case is a spec. Paste an OpenAPI 3.x or Swagger 2.0 URL and the importer reads it. If you only have a docs URL, paste that instead: detection tries the URL itself, then the docs page, then the usual spec locations (/openapi.json, /swagger.json, /swagger/v1/swagger.json, /api-docs), and reports back the spec, the base URL, and the auth type it found. Postman collections, HAR captures, and raw JSON import too, which covers the API whose "spec" is a collection someone on your team exported two years ago.

Some useful APIs never published anything machine readable. For those, AI Spec Discovery reads the documentation and drafts an OpenAPI 3.1 spec of the most useful endpoints. Every endpoint in that draft is marked unverified until a real call succeeds against the real API. It's on Pro and above, with a monthly allowance of runs.

And when you only need two endpoints and don't want to import anything, you can define tools by hand: a name, a description, a method, a path, and a JSON Schema for the inputs.

Keeping credentials off the model

When you register a provider, you tell it how your API expects to be authenticated. The options are a bearer token, an API key in a header (you pick the header name) or in a query parameter, Basic auth, a custom header, or OAuth 2.1 client credentials, where the platform fetches the token, caches it, refreshes it, and retries once on a 401. If the API is public, set it to none.

Whatever you pick, the credential is encrypted at rest and attached to the outbound request at call time, after the model has already decided which tool to call. The model sends a tool name and arguments. The server adds the key, makes the HTTP call, and returns the response. The key never passes through the model, which is the main reason to route through a server at all.

The MCP server has its own front door, separate from your API's. A client can authenticate to it with a bearer token (generated for you and shown once), with an API key, or with OAuth 2.1, which is what lets a client like Claude open a browser and have you sign in instead of pasting a token. The authentication post explains why keeping those two layers straight saves you an afternoon of chasing the wrong 401.

Shaping what the model sees

Wrapping a provider creates an MCP server with a URL and an access token. With auto-discover on, each operation in the spec becomes a tool: the operationId or path becomes the name, the summary becomes the description, and the parameters become a typed input schema. The round-trip post walks through exactly what happens on each call.

Discovery also does some cleanup you'd otherwise do by hand. Operations that exist at /v1, /v2, and /v4 collapse to the highest version. Endpoints that return a zip, a PDF, or a CSV instead of JSON are switched off and sorted last. Names that collide get a numeric suffix so every tool stays reachable. Each tool also ships with MCP annotations derived from its HTTP method, so a GET is marked read-only and a DELETE is marked destructive.

The rest is up to you, and it's where most of the quality comes from. Every tool has an on/off toggle. Descriptions are editable, and they're the only thing the model reads to decide whether a tool applies. A tool can carry a response extraction path, so the model gets the results array instead of the envelope around it. When your API changes, Refresh Tools re-reads the spec and keeps your toggles, your manual tools, and anything you adopted from a suggestion. Too Many Tools is the long argument for spending ten minutes here.

If the spec was written for developers and reads badly to a model, Suggest with AI proposes better names, descriptions, and input schemas, plus which tools to hide. It sees only your tool definitions, never your API or your credentials. Nothing changes until you tick the suggestions you want and click Adopt selected, and every adopted tool has a Revert button. The guardrails post covers what the server refuses to let it change. It's on Pro and above, along with MCP Resources and Prompts.

Running it

A server has two switches. Enabled off means it returns 404 to everything. Live off is maintenance mode: the server still answers initialize and tools/list, so clients stay connected and can see the tools, but it refuses tools/call. If a token leaks, Regenerate Token kills the old one immediately.

Each server has a test page where you can run a tool by hand and see what comes back before an agent does. Upstream calls pass through a rate limiter and a response cache, and a rate-limited upstream comes back with a retry hint instead of a bare error. Outbound requests are checked against loopback, private, and link-local addresses at connection time, so a spec can't point the server at your internal network. Your plan sets the limits on providers, servers, daily requests, requests per minute, and payload size, and the dashboard shows where you are against each.

Seven ways to use it

The capabilities are the same for everyone. What changes is the API and who's on the other end of it.

Put your internal API in Claude Desktop

This is the obvious first use. Your team has an internal service (orders, customers, inventory) with a spec that the framework generates. Wrap it, turn off the admin and maintenance endpoints, and add a few lines to claude_desktop_config.json. Now "what's the status of this order, and who placed it?" is a question you can ask instead of a query you have to write. The Claude Desktop guide covers the config file on each OS and the Connectors route with OAuth.

Let a coding agent call the real API while you build

When you're writing code against an API, Cursor and Claude Code can call it directly instead of guessing at the response shape from docs. Connect the server to the editor and the agent can fetch a real record, look at what actually comes back, and write the parsing code against that. The Cursor guide has the mcp.json setup, and the MCP servers docs have the Claude Code config.

Hand a model a third-party API without handing it the key

The SaaS tools your business runs on mostly have REST APIs with an API key. You can put that key in a prompt, or in an environment variable a local script reads, and hope nothing logs it. Or you register the provider once, the key is encrypted on the server, and the model only ever sees tool names and results. If you want to cut access later, regenerate the server token or switch the server off. The API key itself never left.

Wrap a public API for a quick win

Plenty of public APIs need no key at all. The OpenAPI walkthrough uses the National Weather Service API: paste https://api.weather.gov/openapi.json, set auth to none, wrap it, and Claude can answer "are there any active weather alerts in Colorado right now" with live data. It's a good way to see the whole flow before you point it at anything that matters.

Bring in the API that never shipped a spec

Most teams have one: the vendor API with a docs page, some curl examples, and nothing machine readable. That used to mean transcribing the docs into a spec by hand or giving up. AI Spec Discovery drafts the spec, you wrap it like any other, and the first successful call is what confirms each endpoint.

Split one API into servers by job

One provider can back several MCP servers, each with its own tool selection and its own token. Give the support workflow a server with the read endpoints it needs to look up a customer. Give ops a different server with the endpoints ops actually uses. Each agent reads a short, relevant tool list instead of wading through the other team's tools, and you can revoke one without touching the other.

Clean up a generated spec for agents

If your spec came out of a code generator, the tool list is full of names like getOrdersUsingGET_1 and one-line descriptions. That works for a developer with the docs open and poorly for a model with nothing else to go on. Run Suggest with AI, adopt the renames and descriptions you agree with, and be skeptical of the hides. Refresh Tools won't overwrite what you adopted, so the cleanup survives the next spec change.

Where to start

If you have an API with a spec, wrap it and connect Claude Desktop. It doesn't take long, and it shows you how your API reads to a model, which is usually the most useful thing you'll learn. If you don't have an API in mind, start with weather.gov. The free tier has room for two servers and doesn't ask for a card.

Start free, wrap one API, and turn off every tool you wouldn't hand to a stranger. The docs cover each screen in more detail.