REST API Proxy

Connect any REST API that has an OpenAPI spec to the MCP Gateway — no custom MCP server code needed. The gateway automatically converts OpenAPI endpoints into MCP tools that LLMs can call directly.

How It Works

The REST API proxy bridges the gap between traditional HTTP APIs and the MCP protocol. Instead of writing a custom MCP server wrapper for every API, you point the gateway at an OpenAPI specification and it handles the rest.

1

You provide an OpenAPI specification (JSON or YAML)

2

The gateway parses it into MCP-compatible tool definitions

3

When an LLM calls a tool, the gateway translates it into an HTTP request

4

The API response is returned as MCP tool output

Getting Started

1

Navigate to Servers

Go to MCP Gateway → Servers in the console dashboard.

2

Add a REST API server

Click "Add Server" and select "REST API" as the transport type.

3

Configure the API

Enter the base URL of the API and authentication credentials (if required).

4

Provide the OpenAPI spec

Paste your OpenAPI spec directly, or use auto-discovery to let the gateway find it.

5

Review endpoints

Review the discovered endpoints and toggle off any you don't need.

6

Create the server

Click "Create Server". The gateway will parse the spec and expose each endpoint as an MCP tool, namespaced with the server alias.

Supported Specifications

The gateway supports the following OpenAPI specification versions:

Full

OpenAPI 3.0.x — full support

Full

OpenAPI 3.1.x — full support

Partial

Swagger 2.0 — best-effort compatibility

Tool Name Generation

Each API endpoint becomes an MCP tool. The tool name is generated from the spec:

  • If the spec includes an operationId, it's converted to snake_case (e.g., listPets → list_pets)
  • If no operationId is present, names are derived from HTTP method + path (e.g., GET /users/{id} → get_user)
# Example: A Petstore API connected with alias "petstore"

# operationId: listPets → tool name:
petstore__list_pets

# operationId: createPet → tool name:
petstore__create_pet

# GET /pets/{id} (no operationId) → tool name:
petstore__get_pet

Auto-Discovery

If you don't have the spec URL handy, the gateway can try to find it automatically. When auto-discovery is enabled, the gateway probes common paths on the target API:

/openapi.json
/openapi.yaml
/swagger.json
/v3/api-docs
/api/openapi.json
/.well-known/openapi.json

Tip: Auto-discovery works well with frameworks like FastAPI, Spring Boot, and Express (with swagger-jsdoc) that serve specs at standard paths.

Authentication

REST API servers support the same authentication types as MCP servers. Credentials are forwarded with every request to the upstream API.

  • Bearer token — sent as an Authorization: Bearer <token> header
  • API key — sent as a custom header (e.g., X-API-Key)

Note: OAuth2 authorization flows are not supported. Use a pre-obtained access token instead.

Parameters

The gateway handles four parameter types automatically, mapping them from MCP tool arguments to the correct HTTP request locations:

path

Substituted into the URL (e.g., /users/{id})

query

Appended as query string parameters (e.g., ?limit=10&offset=0)

header

Added as HTTP headers on the request

body

Serialized as a JSON request body

Response Handling

API responses are processed before being returned as MCP tool output:

  • JSON responses are pretty-printed for LLM readability
  • Responses larger than 100 KB are truncated with a notice
  • HTTP 4xx/5xx errors are returned as MCP error responses with the status code and message

Refreshing Specs

When an upstream API changes, use the "Refresh Spec" button on the server detail page to re-parse the OpenAPI specification. The gateway will update tool definitions, adding new endpoints and removing deleted ones.

Limitations

Constraint Detail
Max endpoints per server 200
OAuth2 flows Not supported (use pre-obtained tokens)
Streaming responses Not supported
Deprecated endpoints Automatically skipped

What's Next?