API to MCP: turn an OpenAPI spec into MCP tools

API to MCP conversion turns selected REST operations into tools that an MCP client can discover and call. An OpenAPI document can supply the input schemas and HTTP operation details, but useful tools still need authentication, clear descriptions and sensible limits. AIPx connects supported catalog APIs and existing public MCP servers; it does not import arbitrary OpenAPI specifications.

How API to MCP conversion works

An adapter reads or implements an API’s operations and presents them through MCP tool descriptions. When the client calls a tool, the adapter validates the arguments, builds an HTTP request, applies the correct account credential and returns a result the agent can use.

A specification gives the adapter a starting point. It can describe a path, method, query parameters, request body and response schema. It does not necessarily explain when an agent should call the operation, which account is appropriate or whether the resulting action needs review.

API detail	Possible MCP representation	Design work still needed
Operation ID and summary	Tool name and description	Names should be distinct and useful
Path and query parameters	Tool input fields	Validate identifiers and defaults
JSON request body	Structured input schema	Make required fields unambiguous
Security scheme	Adapter credential handling	Connect the right user or account
Response schema	Tool result structure	Bound size and explain errors
Tags and operation groups	Tool selection groups	Expose the subset the task needs

For example, a list operation may offer pagination parameters but return a large collection by default. A helpful tool should make the bounded page request clear. A mutation may have a technically accurate schema while leaving the consequence poorly described. Review both before offering the tool to a model.

OpenAPI spec to MCP server

There are frameworks and API platforms that perform this conversion. FastMCP documents OpenAPI integration using a schema and an HTTP client, including the from_openapi construction. Kong’s AI MCP Proxy and Microsoft’s API Management MCP support describe exposing managed HTTP operations through MCP.

Those are different deployment models. A framework gives you code and a server runtime to operate. An API platform can expose selected operations from APIs already managed there. A hosted account gateway can connect an existing server without becoming a universal schema converter.

Route	You supply	Who operates the converted server	Useful when
Framework adapter	Schema, HTTP client and server code	You or your infrastructure operator	A custom API needs tailored tools
API-platform conversion	Managed API operations and platform configuration	The platform deployment	Your organization already uses that gateway
AIPx catalog integration	A supported service account	AIPx’s supported integration runtime	The API is already in the catalog
Existing custom MCP connection	Public MCP endpoint and its auth	The upstream server’s operator	The API has already been converted

Do not assume every converter supports every OpenAPI feature, authentication mode or response format. Read that converter’s current documentation and test representative operations. A server that lists tools successfully can still fail at request serialization or provider authorization.

For writing a purpose-built adapter rather than converting everything, see how to build an MCP server.

REST API to MCP

You do not need an OpenAPI file to implement a useful MCP server. A hand-written adapter can offer a few deliberate tools over a REST API. That is often easier to review than exposing hundreds of endpoints whose names were designed for HTTP clients rather than conversational use.

Suppose the task is checking a support ticket and creating a follow-up note. The useful surface may contain two reads and one write. Administrative endpoints for deleting accounts, exporting all records or changing billing settings add little to that task. Select the operations from the job, rather than treating complete API coverage as the goal.

Descriptions should say what the operation returns or changes, which identifiers it expects and whether results may be incomplete. If “update” can replace a whole record rather than patch one field, state that effect. If the API distinguishes a draft from a sent message, preserve that distinction in the tools.

Errors also need translation. An HTTP success with an embedded error object should not be represented as an accomplished task. A rate limit should remain distinguishable from invalid input or insufficient authorization. The agent needs enough result context to decide whether to retry, ask for a missing identifier or stop.

Review pagination and response size

An API’s first page may omit the record the user requested. Conversely, returning an entire history can swamp the conversation and disclose unrelated data. Make pagination explicit, choose small defaults and document whether the tool returns all results or a bounded page.

Large binary files and streaming responses need their own design. An automatically generated input schema does not decide how to present those outputs to a language model. Prefer a concise result or a deliberate retrieval step over silently dumping a large response.

Convert an API to MCP with AIPx

AIPx has two supported connection routes relevant to this category. Neither is an arbitrary OpenAPI upload.

Route 1: connect a supported catalog API

1. Find the service in the integration catalog.
2. Complete its supported account authorization or credential setup.
3. Review the discovered tools for that account.
4. Create an agent and choose its account and tool rules.
5. Copy the agent’s MCP URL and connect the client with OAuth.
6. Run a verifiable read and inspect the audit before trying a change.

The supported integration owns the API-to-tool mapping. You are connecting the account, rather than supplying a new specification for AIPx to interpret. Catalog availability and the upstream account’s privileges define which operations can be used.

Route 2: connect an already-converted custom API

1. Build or operate an MCP adapter for your API using a suitable framework or platform.
2. Make the resulting server reachable at a public URL with appropriate authentication.
3. Add that existing MCP URL in AIPx’s custom MCP connection flow.
4. Use supported automatic OAuth discovery, no-auth access or a configured bearer token as appropriate to that upstream server.
5. Review its discovered tools and agent rules.
6. Connect the AIPx agent endpoint to the chosen client.

The server must already exist. AIPx does not accept your local stdio command, Docker image or arbitrary spec as a deployment request. The remote server guide explains the reachability boundary, and the gateway guide explains the agent endpoint.

Auth: API keys and OAuth

There are at least two credential boundaries in the gateway route. The client authenticates to AIPx; AIPx authenticates to the connected service or custom MCP server. An upstream API key does not substitute for the client’s OAuth token.

A converter must preserve the API’s authentication behavior. A declared security scheme describes requirements but does not supply a valid credential, consent screen or refresh mechanism. Never commit an account key into a shared schema file or put it into a model prompt to compensate for a missing adapter configuration.

AIPx’s client-facing MCP endpoint uses OAuth. Custom upstream MCP connections support their own documented connection methods. Review those methods separately, and use the MCP OAuth guide for client authorization and token boundaries.

AIPx OpenAPI export is the reverse direction

AIPx generates an agent-specific OpenAPI 3.1.0 document at /api/agents/AGENT_ID/openapi. It describes that agent’s permitted tool interface for clients using HTTP APIs. Calls through that interface use X-API-Key protection.

That export is not an import feature. It does not establish which versions of arbitrary incoming OpenAPI schemas AIPx accepts, because there is no general spec-upload route being promised here. It is an additional way to consume the existing configured agent tools.

Limits

The MCP permissions guide explains how to review the resulting tool set, including enforced Hide rules and client-dependent Confirm hints.

Conversion does not repair unclear operation semantics, broad account credentials or provider restrictions. It also does not make every discovered write safe to execute automatically. Review useful task coverage, not merely the number of generated tools.

In AIPx, Hide is enforced server-side and removes access. Allow and Confirm are execution hints, with Confirm requesting client-side approval. Verify the client’s actual handling before relying on confirmation; use Hide when an operation must be unavailable. Provider-level access restrictions remain in force.

AIPx adds a hosted operator and a network dependency. For a private API that must remain within an internal environment, an operated adapter or existing private platform may be a better fit. Free includes three connected accounts and one agent; Pro costs $3 per month with unlimited accounts and agents plus Pro integrations. Upstream costs and rate limits remain separate. Connect free.