From REST API to MCP Server

Many developers are familiar with REST APIs. They are widely used to expose backend services for web and mobile applications. REST APIs define endpoints that accept and return structured data, usually in JSON format.

Recently, a new protocol has emerged to help large language models (LLMs) like Claude or GPT interact with external systems. This is called the Model Context Protocol (MCP). MCP allows AI models to access tools and retrieve information through a common structured interface.

Understanding MCP and REST API fundamentals

A REST API is a set of HTTP endpoints that allow clients to perform operations like retrieving data, submitting forms, or updating records. Each endpoint has a path, method (GET, POST, etc.), and a request/response schema. REST APIs are stateless and rely on HTTP semantics.

An MCP server is a program that exposes tools to an LLM through a defined protocol. Instead of HTTP routes, MCP servers define "tools" that describe what inputs they accept and what outputs they return. These tools are described using JSON Schema and are callable by MCP clients.

The main difference is that REST APIs are designed for traditional software clients, while MCP servers are designed for LLMs. REST APIs expose endpoints over HTTP. MCP servers expose tools through a structured messaging protocol, such as JSON-RPC over HTTP or stdio.

Converting a REST API to an MCP server means wrapping API functionality as tools so that an LLM can call them. This involves defining schemas for each tool, wiring the logic to call the REST API under the hood, and exposing it through the MCP transport.

Key properties of this conversion include:

• AI integration: MCP servers allow LLMs to call external tools through structured interfaces

• Reuse existing logic: Existing REST endpoints can be wrapped without rewriting business logic

• Controlled access: Each tool defines its schema and behavior, allowing fine-grained control

Prerequisites for converting REST to MCP

Before converting a REST API to an MCP server, gather these components:

1. A working REST API with documented endpoints

2. An MCP SDK in a supported language (Python or TypeScript are common)

3. An HTTP client for making requests to the REST API

4. Basic knowledge of JSON Schema for defining tool inputs and outputs

The mapping between REST and MCP components works like this:

Step by step conversion process

1. Set up your development environment

Install an MCP SDK for your language. For Python, you can use:

pip install "mcp[server]

Configure environment variables for your REST API credentials:

2. Define the MCP tools and resources

In MCP, there are two main types of components:

• Tools: Actions that change state (like creating or updating data)

• Resources: Read-only access to data (like retrieving a user profile)

Map each REST endpoint to the appropriate type. A GET /users/{id} endpoint becomes a resource, while a POST /users endpoint becomes a tool.

Here's a simple example of defining a tool in Python:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-api")

@mcp.tool()
def get_user(user_id: str) -> dict:
    """Get user details by ID."""
    response = requests.get(f"{API_BASE_URL}/users/{user_id}", 
                           headers={"Authorization": f"Bearer {API_KEY}"})
    return response.json()

3. Map REST endpoints to MCP handlers

Create handler functions that translate MCP requests into REST requests. These functions receive the tool parameters, make HTTP requests to your API, and return the results.

For a GET request:

def get_product(product_id: str) -> dict:
    response = requests.get(f"{API_BASE_URL}/products/{product_id}")
    return response.json()

For a POST request:

def create_order(items: list, shipping_address: dict) -> dict:
    payload = {
        "items": items,
        "shipping_address": shipping_address
    }
    response = requests.post(f"{API_BASE_URL}/orders", json=payload)
    return response.json()

4. Integrate authentication tokens

Most REST APIs require authentication. Your MCP handlers need to include the right headers when calling the API.

def get_protected_resource(resource_id: str) -> dict:
    headers = {
        "Authorization": f"Bearer {os.environ['API_KEY']}"
    }
    response = requests.get(f"{API_BASE_URL}/resources/{resource_id}", 
                           headers=headers)
    return response.json()

Store credentials in environment variables rather than hardcoding them in your source code.

5. Run and validate basic operations

Start your MCP server and test each tool:

if __name__ == "__main__":
    mcp.run(transport="stdio")  # For local testing

You can test the server using the MCP Inspector tool, which provides a visual interface for calling tools and viewing results.

Handling schema mapping challenges

OpenAPI endpoints don't perfectly map to MCP tools. When converting a REST API to an MCP server, you'll face several schema-related challenges.

First, REST APIs often split parameters across different locations: path, query string, headers, and request body. MCP tools have a single input schema that must combine all these parameters. For example, a REST endpoint like:

Becomes an MCP tool with a unified schema:

{
  "input": {
    "type": "object",
    "properties": {
      "id": { "type": "string" },
      "include": { "type": "string" },
      "limit": { "type": "integer" }
    },
    "required": ["id"]
  }
}

Second, naming collisions can occur when merging parameters from different sources. For example, both the path and query might have an "id" parameter. You'll need to rename these or group them by source.

Third, REST APIs often use $ref to point to reusable schema components. MCP tool schemas must be self-contained, so you need to resolve these references by inlining the referenced schemas.

Finally, recursive references (schemas that refer to themselves) need special handling to avoid infinite expansion. You might need to set a maximum depth or break the recursion at some point.

Handling large APIs dynamically

Many APIs have too many endpoints to be imported at once. MCP currently works by loading all tool schemas for a server into its context. The LLM then chooses which tool to use based on your request.

For APIs with hundreds of endpoints, this approach has limitations:

• Context limits: LLMs have a maximum context size, and too many tool schemas might exceed it

• Cognitive load: Even if the LLM can technically handle all tools, it might struggle to choose the right one

• Performance: Loading all tools slows down initialization and increases memory usage

To handle large APIs, consider these approaches:

1. Create separate MCP servers for different API sections

2. Implement dynamic tool loading based on user intent

3. Create "meta-tools" that help discover and load specific tools on demand

For example, you might start with a discovery tool that finds relevant endpoints based on a description, then dynamically register only those tools.

Testing with MCP Inspector and other clients

After building your MCP server, test it with real clients. The MCP Inspector is a visual tool for testing MCP servers during development.

To use it:

1. Install the MCP CLI: pip install "mcp[cli]"

2. Start your server with the Inspector: mcp dev server.py

3. Open the Inspector in your browser (typically at http://localhost:6274)

4. Select tools, provide inputs, and observe the responses

For production testing, connect your server to actual MCP clients like Claude Desktop or Q CLI. These clients can be configured to use your MCP server by adding entries to their configuration files.

For Claude Desktop, add your server to the MCP configuration:

{
  "mcpServers": {
    "my-api": {
      "command": "python",
      "args": ["/path/to/your/server.py"]
    }
  }
}

Streamable HTTP and remote MCP servers

MCP servers can run locally or remotely. Local servers typically use stdio for communication, while remote servers use HTTP-based transports.

Streamable HTTP is a transport method that allows MCP servers to be exposed over the web. Unlike traditional Server-Sent Events (SSE), Streamable HTTP is completely stateless, making it ideal for serverless environments.

To implement a Streamable HTTP server in Python:

from fastapi import FastAPI
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-api", stateless_http=True)

@mcp.tool()
def hello(name: str) -> dict:
    return {"message": f"Hello, {name}!"}

app = FastAPI()
app.mount("/mcp", mcp.streamable_http_app())

This server can be deployed to any platform that supports FastAPI, such as AWS Lambda, Google Cloud Functions, or traditional servers.

To connect Claude Desktop or Q CLI to a remote MCP server, use a tool like mcp-remote:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-api.example.com/mcp/"
      ]
    }
  }
}

Common pitfalls and troubleshooting

When converting a REST API to an MCP server, watch out for these common issues:

• Schema validation errors: Make sure your tool schemas match the expected input and output formats

• Authentication failures: Check that your API keys or tokens are valid and properly passed to the REST API

• Timeout issues: Long-running REST operations might exceed MCP client timeouts

• API versioning: Changes to the underlying REST API can break your MCP tools if not updated

Here's a quick troubleshooting guide:

Elevate your API experience with MCP

Converting a REST API to an MCP server opens up new possibilities for AI integration. Your existing APIs become accessible to LLMs, allowing them to perform tasks like data retrieval, content creation, or transaction processing on behalf of users.

This approach preserves your investment in REST APIs while adding a new interface layer for AI systems. The MCP server acts as a bridge, translating between the AI world and your existing services.

Tools like Stainless can help automate this process by generating MCP servers directly from OpenAPI specifications. This reduces the manual work of mapping endpoints and defining schemas, especially for large APIs.

Ready to streamline your MCP server development? Get started for free at app.stainless.com/signup.

FAQs about REST API to MCP server

What is the difference between a REST API and an MCP server?

A REST API uses HTTP methods (GET, POST, PUT, DELETE) to allow applications to communicate with servers over the web. An MCP server implements the Model Context Protocol to expose functionality to AI models through structured tools. MCP servers can wrap REST APIs to make them accessible to LLMs.

How do I handle authentication when converting a REST API to MCP?

Store your REST API authentication tokens (like API keys or OAuth tokens) in environment variables or secure storage. Then, include these tokens in the HTTP requests your MCP handlers make to the underlying REST endpoints. Avoid hardcoding credentials in your source code.

What types of REST endpoints work best as MCP tools versus resources?

REST endpoints that retrieve data (GET requests) typically map to MCP resources. Endpoints that create, update, or delete data (POST, PUT, DELETE) work better as MCP tools. Consider the operation's purpose rather than just the HTTP method when deciding.

How can I manage large REST APIs with hundreds of endpoints in MCP?

For large APIs, create logical groupings of endpoints as separate MCP servers, implement dynamic tool loading based on user intent, or create discovery mechanisms that help find relevant tools. This prevents overloading the LLM's context with too many tool definitions.