REST API to MCP Server: A Practical Guide
You already have REST APIs that do useful work. However, AI agents can’t call them directly. They discover and invoke capabilities through the Model Context Protocol, not by reading your OpenAPI spec and guessing. Turning a REST API into an MCP server is what makes your existing business logic callable by an agent. It sounds like a mechanical wrapping exercise, and the naive version is. That’s exactly why so many auto-converted MCP servers are unusable. 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?
A REST API exposes resources over HTTP for developers who read documentation and write integration code. An MCP server exposes tools, along with resources and prompts, with machine-readable schemas. This allows an AI agent to discover what’s available and invoke it without a human integrator. REST is stateless request/response; MCP connections are stateful and built on JSON-RPC 2.0.
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
Map HTTP GET requests to MCP resources for reading data. Map POST, PUT, and DELETE requests to MCP tools for changing state.
Do not convert every route. Select endpoints that match distinct agent actions. Name each tool with a verb-noun pair, such as get_user.
Define tool schemas
An MCP server exposes tool parameters through JSON Schema. The agent validates arguments against this schema before executing a call.
Flatten path, query, and body parameters into a single schema. Give every field a concrete type and precise description. Clear descriptions prevent models from passing wrong arguments.
Wire handlers to call the REST API
A tool handler receives structured inputs, executes the REST request, and returns the response. In a hand-built server this is SDK code. The official MCP SDKs cover Python and TypeScript; fastmcp is a common Python choice). Here’s an example handler:
import httpx
from fastmcp import FastMCP
mcp = FastMCP("User Engine")
@mcp.tool()
def get_user(user_id: int) -> dict:
"""Fetch a user profile by numeric ID."""
url = f"https://api.example.com/users/{user_id}"
response = httpx.get(url)
return response.json()
This handler accepts a user ID from the agent. It runs the HTTP GET request and returns the JSON payload.
Handle authentication
Never pass raw API keys to the agent. Use scoped tokens and store credentials in environment variables or a secrets manager. Use OAuth 2.1 when exposing remote MCP servers. The agent authenticates with the server. The gateway or server exchanges the agent’s token for the downstream API call. See MCP server authentication for the full flow.
Run and test with MCP Inspector
Start the server, connect MCP Inspector, and confirm the agent can discover each tool, sees the right schema, and gets correct results.
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 WSO2
Auto-converting every REST endpoint to an MCP tool fails at scale. If you map, say, 50 API routes, it creates 50 MCP tools. This floods the model's context window with schema noise. Direct REST conversion asks the wrong architectural question. It starts with existing endpoints instead of agent outcomes. An agent-first architecture begins with the task. You build the exact tool an agent needs to finish its work. One composite tool that creates and assigns a ticket is better than three low-level HTTP calls.
WSO2 routes agent traffic through a governed proxy layer rather than running conversion scripts inside the gateway runtime. The WSO2 AI Gateway sits in front of your dedicated MCP servers. It enforces rate limits, manages token authentication, and applies policy guardrails in one place. You maintain central governance across the enterprise while building clean, agent-first tool interfaces.
For more information on how to use AI Gateway and AI Workspace in WSO2 API Platform to build governed MCP servers at scale, see the following resources:
Frequently Asked Questions
Can you turn a REST API into an MCP server? Yes. You map selected endpoints to MCP tools with machine-readable schemas, wire each tool’s handler to call the REST endpoint, and secure it. Tools like the WSO2 AI Gateway can generate the server directly from an OpenAPI definition.
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? Read-only GETs map naturally to resources or read tools; state-changing POST/PUT/DELETE map to tools (actions) with appropriate access controls.
How is a REST API different from an MCP server? REST is stateless HTTP for human developers; MCP is a stateful, JSON-RPC protocol with machine-readable tool schemas so AI agents can discover and invoke capabilities on their own.
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
Converting a REST API to an MCP server is less about wrapping and more about curation: choose the operations agents need, give them schemas and names a model can reason about, and secure the whole thing. Hand-building one server teaches you the moving parts; a gateway that generates servers from your OpenAPI specs is how you do it across an enterprise without reinventing auth, rate limiting, and discovery each time.
