mcp-api-gateway
Allows interacting with the GitHub API, enabling operations such as managing repositories, creating issues, and user management via automatically generated tools from GitHub's Swagger specification.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-api-gateway list all pets from the Petstore API"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
api-gateway
A universal MCP (Model Context Protocol) server to integrate any API with Claude Desktop using only Docker configurations. Point it at any Swagger/OpenAPI spec and it automatically generates tools that Claude can use.
Available on the Docker MCP Toolkit.
Quick Installation
Using Docker MCP Toolkit (Recommended)
The easiest way to get started is through the Docker MCP Toolkit, which provides one-click setup with Docker Desktop.
Using Docker Hub
Add to your claude_desktop_config.json:
{
"mcpServers": {
"my-api": {
"command": "docker",
"args": [
"run", "--rm", "-i", "--pull", "always",
"-e", "API_1_NAME=my-api",
"-e", "API_1_SWAGGER_URL=https://api.example.com/swagger.json",
"-e", "API_1_BASE_URL=https://api.example.com/v1",
"-e", "API_1_HEADER_AUTHORIZATION=Bearer YOUR_TOKEN",
"rflpazini/mcp-api-gateway:latest"
]
}
}
}Using npx
API_1_NAME=my-api \
API_1_SWAGGER_URL=https://api.example.com/swagger.json \
API_1_BASE_URL=https://api.example.com/v1 \
npx mcp-api-gatewayLocal Build
git clone https://github.com/rflpazini/mcp-api-gateway
cd mcp-api-gateway
docker build -t mcp-api-gateway .
docker run --rm -it \
-e API_1_NAME=test \
-e API_1_SWAGGER_URL=https://petstore.swagger.io/v2/swagger.json \
-e API_1_BASE_URL=https://petstore.swagger.io/v2 \
mcp-api-gatewayRelated MCP server: OpenAPI MCP Server
Configuration
Core Variables
Variable | Description | Required | Default |
| Unique API name | Yes | — |
| Swagger/OpenAPI spec URL | Yes | — |
| API base URL (overrides spec) | No | From spec |
| Custom headers (e.g., | No | — |
| JSON object with multiple headers | No | — |
Performance Tuning
For large APIs with hundreds of endpoints, these variables reduce the tool list payload sent to Claude:
Variable | Description | Default |
|
|
|
|
|
|
| Comma-separated path prefixes to include (e.g., | All paths |
| Comma-separated OpenAPI tags to include (e.g., | All tags |
| Comma-separated parameter names to strip from schemas (e.g., | None |
Reliability
Variable | Description | Default |
| Request timeout in milliseconds |
|
| Max retry attempts for 429/5xx errors (exponential backoff) |
|
| Max response size in bytes before truncation |
|
Performance Results
Tested with a 925-endpoint enterprise API:
Configuration | Tools | Payload | Reduction |
No optimization | 1093 | 2,269 KB | — |
| 1093 | 633 KB | 72% |
| 53 | 184 KB | 92% |
| 94 | 50 KB | 98% |
Recommendation: Use API_N_TOOL_MODE=grouped for any API with more than 50 endpoints.
Examples
Simple API with Authentication
{
"mcpServers": {
"github-api": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "API_1_NAME=github",
"-e", "API_1_SWAGGER_URL=https://api.github.com/swagger.json",
"-e", "API_1_HEADER_AUTHORIZATION=token ghp_xxxxxxxxxxxx",
"rflpazini/mcp-api-gateway:latest"
]
}
}
}Large API with Grouped Tools
{
"mcpServers": {
"enterprise-api": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "API_1_NAME=myapi",
"-e", "API_1_SWAGGER_URL=https://api.company.com/v3/api-docs",
"-e", "API_1_BASE_URL=https://api.company.com",
"-e", "API_1_TOOL_MODE=grouped",
"-e", "API_1_SCHEMA_MODE=compact",
"-e", "API_1_HEADER_AUTHORIZATION=Bearer your_token",
"rflpazini/mcp-api-gateway:latest"
]
}
}
}Multiple APIs
Configure multiple APIs by incrementing the index (API_1_*, API_2_*, API_3_*):
{
"mcpServers": {
"company-apis": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "API_1_NAME=users",
"-e", "API_1_SWAGGER_URL=https://api.company.com/users/swagger.json",
"-e", "API_1_HEADER_X_API_KEY=users_key_123",
"-e", "API_2_NAME=products",
"-e", "API_2_SWAGGER_URL=https://api.company.com/products/openapi.yaml",
"-e", "API_2_HEADER_AUTHORIZATION=Bearer products_token",
"-e", "API_3_NAME=orders",
"-e", "API_3_SWAGGER_URL=https://api.company.com/orders/spec.json",
"-e", "API_3_HEADERS={\"Authorization\":\"Bearer token\",\"X-Tenant\":\"company123\"}",
"rflpazini/mcp-api-gateway:latest"
]
}
}
}Filtered Endpoints
Only load specific parts of a large API:
{
"mcpServers": {
"filtered-api": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "API_1_NAME=myapi",
"-e", "API_1_SWAGGER_URL=https://api.company.com/swagger.json",
"-e", "API_1_PATH_PREFIX=/api/v3/users,/api/v3/orders",
"-e", "API_1_SCHEMA_MODE=compact",
"-e", "API_1_EXCLUDE_PARAMS=_clientRegion,_platform",
"rflpazini/mcp-api-gateway:latest"
]
}
}
}Local Swagger File
Mount a local Swagger file into the container:
{
"mcpServers": {
"local-api": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-v", "/path/to/swagger.yaml:/swagger.yaml",
"-e", "API_1_NAME=local-api",
"-e", "API_1_SWAGGER_URL=file:///swagger.yaml",
"-e", "API_1_BASE_URL=http://host.docker.internal:3000",
"rflpazini/mcp-api-gateway:latest"
]
}
}
}Features
Cookie-Based Authentication
The server automatically persists cookies across requests. When an API returns Set-Cookie headers (e.g., after a login call), those cookies are stored and replayed on subsequent requests to the same API. No configuration needed.
Grouped Tools
When API_N_TOOL_MODE=grouped is set, endpoints are automatically grouped into resource tools:
Tagged APIs: Groups by OpenAPI tag (e.g., all
/usersendpoints become onemyapi_Userstool)Untagged APIs: Infers groups from path structure (e.g.,
/pets,/store)Each grouped tool lists available operations in its description, and the LLM selects which one to call via an
operationparameter
Health Check
A built-in check_api_health tool lets Claude verify API connectivity. It pings each configured API's base URL and reports reachability, HTTP status, and response time.
Retry with Backoff
Failed requests (429, 500, 502, 503, 504) are automatically retried with exponential backoff. The server honors Retry-After headers from rate-limited APIs.
Using in Claude
Available Commands
View available APIs: "What APIs are configured?"
Explore endpoints: "How do I create a user?" / "What parameters do I need?"
Execute operations: "Create a user named John with email john@email.com"
Check health: "Is the API reachable?"
Security
Best Practices
Never commit tokens: Use environment variables or secrets
Use limited scope tokens: Only necessary permissions
Rotate tokens regularly: Update your tokens periodically
Always use HTTPS: Ensure your APIs use HTTPS
Docker Image Security
The production image uses Google Distroless as the runtime base:
No shell, no package manager, no OS utilities
Runs as non-root user
0 known vulnerabilities
Node.js 24 LTS (supported until April 2028)
Troubleshooting
API not showing up
Check if the Swagger URL is accessible from the container
Confirm environment variables are correct (especially
API_N_SWAGGER_URL)Check logs:
docker logs <container_id>
Authentication error
Verify token is correct
Confirm header format (Bearer, Basic, etc)
For cookie-based auth: ensure the login endpoint is called first
Too many tools / slow startup
Use
API_N_TOOL_MODE=groupedto reduce tool countUse
API_N_PATH_PREFIXorAPI_N_TAGSto filter endpointsUse
API_N_SCHEMA_MODE=compactto reduce schema size
Request timeouts
Increase timeout:
API_N_TIMEOUT=60000Check API latency directly
Contributing
PRs are welcome! Some ideas:
OAuth authentication support
Smart response caching
WebSocket support
Web configuration interface
Metrics and observability
License
MIT License - see LICENSE file for details.
Available Tools
3 toolscheck_api_healthB
Check connectivity and health of configured APIs
Inputs: api_name.
execute_apiC
Execute any API endpoint with custom parameters
Inputs: path (required), method (required), api_name (required), data, +2 more.
get_api_infoA
Get information about available APIs and their endpoints
Inputs: api_name.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clear, distinct purpose: get_api_info retrieves metadata, check_api_health tests connectivity, and execute_api performs API calls. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern (get_api_info, check_api_health, execute_api) using snake_case. The naming is uniform and predictable.
Three tools is an appropriate scope for an API gateway server, covering information retrieval, health checking, and execution without being excessive or insufficient.
The tools cover the core functions of an API gateway: discovery, health, and execution. Minor gaps like authentication management or rate limiting are missing but not critical for basic use.
Maintenance
Related MCP Connectors
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Host any HTTP API as a standard MCP server; auto-distribute to 12+ mainstream agent platforms.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
MCP server for AI access to Swagger by SmartBear.
Related MCP Servers
AlicenseNot gradedqualityCmaintenanceAn MCP server that enables dynamic tool registration and execution based on API definitions, providing seamless integration with services like Claude.ai and Cursor.ai.23MIT- AlicenseNot gradedqualityDmaintenanceA generic MCP server that dynamically converts OpenAPI-defined REST APIs into tools for LLMs like Claude. It supports multiple authentication methods and transport protocols, enabling seamless interaction with any OpenAPI-compliant API.15 npmMIT
- AlicenseNot gradedqualityDmaintenanceConverts any OpenAPI/Swagger spec into an MCP server, exposing REST API endpoints as tools for Claude.MIT
- FlicenseNot gradedqualityDmaintenanceAutomatically converts OpenAPI specifications into MCP servers, allowing tools like Claude Desktop to interact with your REST APIs through a standard protocol.-