mcp-api-gateway

The mcp-api-gateway server provides a universal MCP (Model Context Protocol) integration layer for Claude Desktop that connects to external APIs via Docker. It reads API definitions from environment variables and exposes those APIs to Claude through a consistent set of endpoints described by the Swagger/OpenAPI documents you provide. Users can view available APIs, explore endpoints, and execute operations against those APIs directly from Claude, making it straightforward to plug in external services without writing custom integrations. The CLI-style Claude prompts map to API actions such as listing endpoints, querying resources, creating new records, or performing domain-specific operations, all mediated by the gateway container.

In Claude, you can:

• View available APIs configured in the gateway and list their endpoints.
• Explore API operations and required parameters for actions like creating, updating, or querying data.
• Execute operations by issuing natural-language prompts (e.g., create a new user, fetch orders, update a product) and let the gateway translate those prompts into REST calls against your Swagger-defined API. The gateway handles header management, authentication tokens, and per-API configuration through the provided environment variables.

Prerequisites:

• Docker installed on your machine or server where Claude Desktop will run.
• Access to a Docker registry hosting the mcp-api-gateway image (public or private with appropriate credentials).

1. Install Docker

• Follow the official Docker installation guide for your platform: https://docs.docker.com/get-docker/

2. Pull or build the gateway image

• Pull from Docker Hub (preferred for quick start): docker pull rflpazini/mcp-api-gateway:latest
• Or build locally from the repository: git clone https://github.com/rflpazini/mcp-api-gateway cd mcp-api-gateway docker build -t mcp-api-gateway .

3. Configure environment variables for your API(s)

• Decide on a unique API name (e.g., my-api) and set the following environment variables: API_1_NAME: Unique API name API_1_SWAGGER_URL: Swagger/OpenAPI file URL API_1_BASE_URL: Optional base URL to override Swagger API_1_HEADER_AUTHORIZATION: Optional Authorization header value

4. Run the gateway container

• Example using Docker (adjust values to your setup): docker run --rm -i
  -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

5. Integrate with Claude Desktop

• Update your claude_desktop_config.json (or equivalent) to include the mcpServers section as shown in the Quick Installation example, referencing the same image and environment settings used above.
• Launch Claude Desktop and verify that the gateway appears under available MCP servers and exposes the configured APIs.

Tips and known considerations:

• Use unique API_N_NAME values for each API you want to expose through the gateway.
• If you need multiple APIs, you can configure API_2_NAME, API_3_NAME, etc., within the same docker run command by adding additional -e API_2_NAME, API_2_SWAGGER_URL, etc., and exposing multiple endpoints via your Swagger/OpenAPI documents.
• For sensitive tokens, prefer secrets management or environment variable injection rather than hard-coding values in config files.
• If an API’s Swagger URL changes, update the corresponding API_N_SWAGGER_URL and restart the container.
• When debugging, inspect container logs with docker logs <container_id> to diagnose issues like unreachable Swagger URLs or invalid environment variables.
• Ensure the API endpoints are accessible over HTTPS in production; use proper certificate management for secure communication.