REST API to MCP server: A practical guide
Abu Sakib·9 min read
On this page
- REST API vs. MCP: What’s the difference?
- Should you convert your REST API to MCP? (Design for outcomes)
- Prerequisites
- How to convert a REST API to an MCP server (step by step)
- Handling schema mapping and large APIs
- Local vs. remote MCP servers (transports)
- Doing this at scale with Choreo API Management
- Frequently asked questions
- Conclusion
To expose a REST API through MCP, select the operations an agent needs, describe them as tools, and implement handlers that call the existing API. The API remains the system of record; the MCP server supplies a discoverable interface for compatible clients.
Agents can also call REST APIs through application-defined functions or other integrations. MCP is useful when you want a shared discovery and invocation interface across clients, rather than a separate adapter for each application. This guide covers the difference between REST and MCP, when conversion is worth it, the step-by-step, and how to do it at scale.
REST API vs. MCP: What’s the difference?
REST describes an approach to designing resource-oriented APIs. MCP defines a JSON-RPC interface through which compatible applications discover and use server capabilities. A single system can expose the same business operation through both interfaces. Do not define the distinction as stateless REST versus stateful MCP: revision 2026-07-28 makes MCP stateless at the protocol level, while application workflows can still keep their own state.
A model, not a developer, reads an MCP tool description. Names and descriptions are part of the interface. get_customer_profile with a clear description is a good tool, contrary to endpoint_v2_get, even though both wrap the same call.
Should you convert your REST API to MCP? (Design for outcomes)
Do not convert every REST endpoint into an agent tool. Auto-converting a 200-endpoint API fills the context window with raw schema data. This noise lowers the model's tool selection accuracy. Group related routes into a few specific tools instead. Convert for outcomes the agent actually needs:
-
Select, don’t dump. Expose the handful of operations that map to real agent tasks, not the entire surface.
-
Compose where it helps. A single “create and assign ticket” tool beats three chained low-level calls.
-
Prefer read-only first. Start by exposing safe reads, then add write operations with explicit access controls.
Turn an endpoint into a tool only if it represents a single action an agent intentionally chooses.
Prerequisites
-
A running REST API with an OpenAPI/Swagger definition (or the ability to produce one).
-
Credentials/auth for that API.
-
An MCP-capable client or an MCP testing tool (MCP Inspector) to validate the server.
How to convert a REST API to an MCP server (step by step)
Map endpoints to tools and resources
Choose the MCP primitive by how the client should use the capability, not by the downstream HTTP method. A tool may perform a read or a write. A resource exposes contextual data through a URI for the application to retrieve.
| REST operation | Proposed MCP interface | Reason |
|---|---|---|
GET /customers/{id} | get_customer tool | Agent requests a customer lookup |
| GET /policies/refunds | policy resource | Application retrieves reference material |
| POST /tickets | create_ticket tool | Agent requests a state-changing action |
Expose only the fields and actions needed for the task. Check authorization independently for both read and write operations.
Define tool schemas
Define the tool's input contract with JSON Schema. The server must validate incoming arguments before calling the backend; model-generated arguments are untrusted input. Descriptions help tool selection but do not replace validation or authorization.
This illustrative input schema accepts one positive integer and rejects additional fields:
{
"type": "object",
"properties": {
"user_id": {"type": "integer", "minimum": 1, "description": "Numeric identifier of the user to retrieve"}
},
"required": ["user_id"],
"additionalProperties": false
}
Wire handlers to call the REST API
The handler validates the input, checks that the caller may access the requested record, and sends an authenticated request to a fixed backend. Use a bounded timeout, handle unsuccessful HTTP responses explicitly, and return only the fields the tool promises.
For get_user, use this implementation contract:
| Condition | Required behavior |
|---|---|
| user_id is invalid | Reject before a backend request |
| Caller lacks record access | Return an authorization failure without disclosing the record |
| Backend returns 200 | Validate and return the permitted user fields |
| Backend returns 404 | Return a stable not-found result |
| Backend times out | Return a bounded failure; do not retry indefinitely |
| Backend returns unexpected content | Return a safe error and log diagnostic details outside the tool response |
For a generated-server implementation, follow the Arazzo MCP Generator quick start. It uses an Arazzo workflow and referenced OpenAPI files to generate a Dockerized Python MCP server. Generation is a starting point: review the tool contract, credentials and error behavior before exposing it to clients.
Handle authentication
Separate authentication to the MCP server from authentication to the backend API. For a protected HTTP MCP server, implement the MCP authorization flow and validate that the token is intended for that server. Do not forward an incoming bearer token to an unrelated downstream API.
The backend call needs credentials intended for that backend and the required permissions. Whether this uses a service credential or delegated user authorization depends on the backend's security model. Store secrets outside tool arguments and responses. Enforce resource-level authorization before returning data or changing state.
See the MCP authorization specification and security guidance for token handling and trust boundaries.
Run and test with MCP Inspector
Connect an MCP-compatible test client and verify discovery and invocation separately. Record the client, server and protocol versions used for the test.
- Discover tools and confirm that names, descriptions and schemas match the published contract.
- Call get_user with an allowed identifier and verify the expected fields.
- Send an invalid identifier and confirm no backend request is made.
- Request a record the caller cannot access and confirm that no private fields are returned.
- Simulate a backend timeout and confirm a bounded failure.
- Review logs for a correlation identifier and outcome, and confirm they contain no bearer tokens or raw credentials.
These are acceptance tests for the adapter, not evidence that the model will always choose the right tool. Test representative agent tasks separately.
Handling schema mapping and large APIs
Conversions go wrong in large APIs. Mirroring every endpoint creates parameter bloat that confuses the model. Flatten nested HTTP parameters into simple schemas with clear descriptions. Normalize backend HTTP errors into standard JSON responses. Predictable errors help the model recover when a request fails.
Handle pagination inside the tool handler. Auto-paginate small datasets or expose explicit cursors for large lists. Treat every tool schema as an immutable contract. Version your schemas deliberately so active agent workflows do not break. The goal is to have a few reliable tools instead of copying every REST endpoint.
Local vs. remote MCP servers (transports)
MCP servers communicate through stdio or streamable HTTP. A local server uses stdio on the client machine for desktop tools. A remote server streams HTTP across a network.
Wrapping a REST API for team-wide use almost always means a remote server. And networked servers require authentication, rate limiting, and governance, because now many agents share one networked entry point.
Doing this at scale with Choreo API Management
Keep server generation and traffic governance separate in the architecture. Choreo Labs' Arazzo MCP Generator turns workflow specifications and referenced OpenAPI definitions into a server implementation. Choreo Agent Control Plane can configure a proxy in front of an upstream MCP server and apply gateway policies. These are distinct responsibilities even when used in the same deployment.
Start with a small tool set and expand it when task-based evaluation demonstrates a need. An operation count alone does not prove that an interface will succeed or fail. Measure tool selection, argument correctness and end-to-end task completion.
For more information on how to use AI Gateway and Choreo Agent Control Plane in Choreo API Management to build governed MCP servers at scale, see the following resources:
- Getting started with Choreo Agent Control Plane
- Setting up an AI Gateway in Choreo Agent Control Plane
- MCP Proxies overview
Frequently asked questions
Can you turn a REST API into an MCP server? Yes. Map selected endpoints to MCP tools with machine-readable schemas, wire each handler to call the REST endpoint, and secure it. Choreo Labs' Arazzo MCP Generator can generate a server implementation from an OpenAPI definition; Choreo Agent Control Plane separately applies gateway policy to the deployed server.
Should I convert every endpoint to a tool? No. Auto-converting an entire API floods the agent with tools and hurts its tool selection. Expose only the operations that map to real agent tasks, starting with read-only ones.
How do GET and POST map to MCP? Choose the MCP primitive by how a client should use the capability, not by the HTTP method alone. A tool can perform a read or a write; a resource exposes contextual data for retrieval.
How is a REST API different from an MCP server? REST is a resource-oriented API style. MCP is a JSON-RPC interface for discovering and invoking server capabilities; revision 2026-07-28 makes it stateless at the protocol level, though applications can still maintain their own state.
How do I secure a converted MCP server? Never give the agent raw API credentials. Use OAuth 2.1 for remote servers, scoped tokens, and secrets management, ideally enforced at a gateway.
Conclusion
A useful REST-to-MCP adapter preserves backend authorization while giving clients a clear, testable tool contract. Select the operations, validate arguments, secure both connections and test failure behavior. When several teams need shared controls, compare MCP gateways and proxies using the policies your deployment must enforce.