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-gateway

Local 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-gateway

Configuration

Core Variables

Performance Tuning

For large APIs with hundreds of endpoints, these variables reduce the tool list payload sent to Claude:

Reliability

Performance Results

Tested with a 925-endpoint enterprise API:

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 /users endpoints become one myapi_Users tool)
• 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 operation parameter

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

1. View available APIs: "What APIs are configured?"
2. Explore endpoints: "How do I create a user?" / "What parameters do I need?"
3. Execute operations: "Create a user named John with email john@email.com"
4. Check health: "Is the API reachable?"

Security

Best Practices

1. Never commit tokens: Use environment variables or secrets
2. Use limited scope tokens: Only necessary permissions
3. Rotate tokens regularly: Update your tokens periodically
4. 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=grouped to reduce tool count
• Use API_N_PATH_PREFIX or API_N_TAGS to filter endpoints
• Use API_N_SCHEMA_MODE=compact to reduce schema size

Request timeouts

• Increase timeout: API_N_TIMEOUT=60000
• Check 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.