Gateway

Gateway MCP Server acts as a single entry point that routes MCP requests to multiple backend MCP servers, manages their lifecycles, and runs in a Docker-based isolated environment. This gateway simplifies connecting MCP clients to diverse backends and handles automatic process management so you can focus on building integrations.

How to use

You connect MCP clients to Gateway MCP Server, which intelligently routes requests to the configured backend MCP servers. Use the gateway to access multiple backends through one entry point, while each backend runs separately in its own container. To start, ensure the gateway is running and your backends are defined in the configuration. Then use your MCP client to call tools on a specific backend or to discover available tools across backends.

How to install

Prerequisites for installation include Docker and MCP clients compatible with the gateway. Follow these concrete steps to set up the gateway and its backends.

1. Clone the project and prepare the directory.

2. Ensure Docker is installed and running on your system.

3. Create or obtain the configuration files for the gateway and backends. You will typically place a config.json that defines backend servers and environment variables.

4. Prepare an environment variable file if you plan to source tokens or API keys from a .env file.

5. Start the gateway using Docker with the provided configuration, mounting the necessary files and Docker socket as shown in the configuration example.

Configuration and usage notes

Gateway MCP Server is configured to run backend MCP servers as Docker containers. The gateway itself runs in a container and uses stdio to communicate with each backend. You mount the gateway’s config and environment into the gateway container and provide access to the Docker daemon so that backends can be launched as containers.

Example configuration for a backend gateway entry (stdio). This example starts the gateway as a Docker container, mounts the gateway config, shares the Docker socket, and loads environment variables from a file.

{
  "mcpServers": {
    "gateway": {
      "type": "stdio",
      "name": "gateway",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/mcpware/config.json:/app/config.json:ro",
        "-v",
        "/var/run/docker.sock:/var/run/docker.sock",
        "--env-file",
        "/path/to/mcpware/.env",
        "mcpware"
      ]
    }
  }
}

Important notes: replace /path/to/mcpware with the absolute path to your configured gateway project. Mounting the Docker socket at /var/run/docker.sock is required for launching Docker-based backends.

Environment variables

Environment variables used by the gateway and backends are loaded from an environment file and can be referenced in configurations. Common examples include access tokens and API keys.

GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_GITHUB_TOKEN
BUILDKITE_API_TOKEN=YOUR_BUILDKITE_TOKEN
ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY

Tools and capabilities

Gateway MCP Server provides two core tooling capabilities for MCP clients: use_tool routes a tool call to a specific backend, and discover_backend_tools queries the available tools on backends. These tools enable you to execute actions on backends and explore what each backend offers.

Available tools

use_tool

Routes a tool call to a specific backend server with defined tool arguments.

discover_backend_tools

Discovers available tools on configured backends, optionally filtering by backend.