# How to Build Custom MCP Servers from OpenAPI Specifications: A Complete Guide

> Learn to build custom MCP servers from OpenAPI specs. Our guide details conversion frameworks that map REST to MCP tools, enabling LLM agents to discover and invoke your API.

- Repository: [Frank Fiegel/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers)
- Tags: how-to-guide
- Published: 2026-09-06

---

**You can build custom MCP servers from existing OpenAPI specifications by using conversion frameworks that automatically map REST endpoints to Model Context Protocol tools, enabling LLM agents to discover and invoke your API through natural language prompts.**

The Model Context Protocol (MCP) standardizes how AI agents interact with external data sources and tools. When you have an existing REST API documented with OpenAPI (or Swagger), converting it into an MCP server allows Claude, Cursor, and other LLM clients to consume your endpoints without custom integration code. The `punkpeye/awesome-mcp-servers` repository catalogs the essential tools and community implementations that make this conversion possible.

## Understanding the Conversion Architecture

Converting an OpenAPI specification into an MCP server involves three core components working together. The **OpenAPI spec** serves as the source of truth for endpoint definitions, request/response schemas, and security schemes. The **MCP conversion layer** reads this specification and generates MCP tool definitions—either as meta-tools (`list`, `get`, `call`) or as individual per-endpoint tools. Finally, **authentication tools** within the MCP server handle token storage and state management, allowing agents to make secure, stateless calls to your underlying API.

## Step-by-Step Implementation

### Choose a Conversion Framework

Several open-source projects automate the mapping from OpenAPI to MCP. According to the `punkpeye/awesome-mcp-servers` source code, these are the primary options:

- **openapi-mcp-gateway** – Mounts multiple OpenAPI specifications in a single process, generating three meta-tools (`list`, `get`, `call`) that proxy requests to each endpoint.
- **openapi-to-mcp** – A lightweight Python-based server that converts any OpenAPI spec into callable MCP tools, supporting OAuth2, API-Key, and Basic authentication schemes.
- **openapi-mcp** – A Dockerized MCP server that directly wraps an existing OpenAPI document without requiring local installation.

### Prepare Your OpenAPI Document

Ensure your specification is a valid JSON or YAML file using OpenAPI 3.x (version 2.0/Swagger is also supported). Critically, define all security schemes—Bearer tokens, API keys, or OAuth2 flows—within the spec. The conversion layer exposes these as MCP authentication tools, and missing definitions will prevent the LLM from properly authorizing requests.

### Run the Conversion Server

Most frameworks support single-command installation and execution. For example, using **openapi-to-mcp**:

```bash

# Install the converter

pip install openapi-to-mcp

# Launch the MCP server pointing at your spec

OPENAPI_SPEC=https://example.com/openapi.yaml \
openapi-to-mcp --host 0.0.0.0 --port 8080

```

The server exposes an HTTP endpoint (`/mcp`) that conforms to the Model Context Protocol. Each operation in your OpenAPI document becomes an individual MCP tool (e.g., `listCustomers`, `createOrder`). For Dockerized deployments, the **openapi-mcp** project allows you to mount your spec file as a volume without installing Python dependencies locally.

### Configure Authentication for LLM Agents

The generated MCP server automatically creates authentication tools (e.g., `setBearerToken`, `setApiKey`). Agents must call these before invoking business-logic endpoints:

```python
import requests

MCP_URL = "http://localhost:8080/mcp"

# Store authentication credentials

requests.post(
    f"{MCP_URL}/setBearerToken",
    json={"token": "sk_test_4eC39HqLyjWDarjtT1zdp7dc"}
)

```

This approach ensures secure access without hard-coding secrets in the agent's configuration, as credentials are stored in the server's session state.

### Register with Your MCP Client

Add the server URL to your agent's configuration file. For Claude Desktop, modify the configuration to include:

```json
{
  "mcpServers": [
    {
      "name": "MyShop-MCP",
      "url": "http://localhost:8080/mcp"
    }
  ]
}

```

Cursor and other MCP-compatible clients use similar JSON manifests to discover available tools through the MCP registry.

## Working with Generated Tools

Once registered, test the integration by asking the agent to perform operations against your API. The LLM automatically resolves natural language requests to the appropriate MCP tool, handles authentication, and executes HTTP calls.

For programmatic testing in Python:

```python
import requests
import json

MCP_URL = "http://localhost:8000/mcp"

# 1. Set authentication (if not already set)

requests.post(
    f"{MCP_URL}/setBearerToken",
    json={"token": "sk_test_4eC39HqLyjWDarjtT1zdp7dc"}
)

# 2. Call a generated endpoint

resp = requests.post(
    f"{MCP_URL}/listCustomers",
    json={"limit": 5}
)
print(json.dumps(resp.json(), indent=2))

```

To test with a public API, point `OPENAPI_SPEC` to the raw OpenAPI definition (e.g., Stripe's public spec) and query endpoints like `listCustomers` or `createCharge`.

## Repository Structure and Community Resources

The `punkpeye/awesome-mcp-servers` repository contains several key files relevant to building and publishing custom MCP servers:

- **[`README.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README.md)** – Lists and categorizes community-maintained MCP implementations, including the OpenAPI-based conversion servers referenced above.
- **[`opencode.json`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/opencode.json)** – Metadata used by the Opencode environment for automated discovery and analysis of MCP projects.
- **[`CONTRIBUTING.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/CONTRIBUTING.md)** – Guidelines for submitting new MCP servers to the curated list, which you should follow once you publish your custom OpenAPI conversion server.

These files provide the ecosystem context and standards for ensuring your MCP server integrates properly with existing tooling.

## Summary

- **Conversion frameworks** like `openapi-to-mcp`, `openapi-mcp-gateway`, and `openapi-mcp` eliminate the need to manually rewrite REST APIs as MCP tools.
- **Authentication tools** generated from your OpenAPI security schemes allow LLM agents to manage tokens and API keys securely without exposing secrets in configurations.
- **One-command deployment** is possible using pip-installed Python packages or Docker containers, with the server exposing a standard `/mcp` endpoint.
- **Registration** involves adding a JSON manifest to your MCP client (Claude Desktop, Cursor, etc.) to enable automatic tool discovery.
- **Community standards** are maintained in the `punkpeye/awesome-mcp-servers` repository, which catalogs implementations and provides contribution guidelines via [`README.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README.md) and [`CONTRIBUTING.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/CONTRIBUTING.md).

## Frequently Asked Questions

### What version of OpenAPI is required to build an MCP server?

OpenAPI 3.x is preferred, though 2.0 (Swagger) specifications are also supported by most conversion frameworks. The key requirement is that the document must be valid JSON or YAML with explicitly defined security schemes, as these determine how the MCP server generates authentication tools.

### How does authentication work between the LLM and my API?

The MCP conversion layer reads your OpenAPI spec's security definitions and exposes them as separate tools (e.g., `setBearerToken`, `setApiKey`). When an agent needs to access a protected endpoint, it first calls the appropriate authentication tool to store credentials in the server's session. Subsequent tool invocations use these stored credentials to authorize requests to your underlying REST API.

### Can I convert multiple OpenAPI specifications into a single MCP server?

Yes, the **openapi-mcp-gateway** framework is specifically designed to mount many OpenAPI specs in a single process. It generates three meta-tools (`list`, `get`, `call`) that proxy requests to any registered endpoint, making it ideal for microservice architectures or API gateways managing multiple services.

### Where should I publish my custom MCP server once it's built?

Submit your project to the `punkpeye/awesome-mcp-servers` repository by following the guidelines in [`CONTRIBUTING.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/CONTRIBUTING.md). The repository maintains a curated list of MCP implementations in [`README.md`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README.md), and inclusion requires providing metadata about your server's capabilities, transport method, and installation instructions.