MCP Gateway sits between your AI client and your tool backends. It presents a small, fixed set of meta-tools that the AI can use to discover and invoke tools on demand, instead of loading every tool definition into every request. The gateway handles discovery, routing, and resilience, so your AI session can stay lightweight while still accessing a large toolbox. The core meta-tools are gateway_search_tools for finding the right tool, and gateway_invoke for executing the chosen tool. Tools load on demand and can be updated hot-reloaded via YAML definitions or REST API specifications, with minimal latency.

To use it, run the gateway and point your MCP-enabled AI client at localhost:39400 (or the configured port). Provide capability definitions (YAML) under your capability directory or import OpenAPI specs to auto-generate capabilities. The gateway will hot-reload YAML capabilities in ~500ms and route requests to the appropriate tool backends. If you want REST APIs turned into MCP tools, you can import OpenAPI specs and begin using them as capabilities without writing MCP servers yourself. The system is designed for resilience: circuit breakers, retries, rate limiting, and health checks ensure stability even when some backends misbehave.

Prerequisites:

• Docker installed and running
• Access to a local or remote container registry (optional if using prebuilt images)
• Basic knowledge of YAML-based capability definitions (optional for starter capabilities)

1. Install Docker (example for Linux/macOS):

   • macOS: install Docker Desktop from https://www.docker.com/products/docker-desktop
   • Linux: follow the official guide for your distro (often involves sudo apt install docker.io and sudo usermod -aG docker $USER)

2. Pull or build the MCP Gateway image

   • If you use a prebuilt image: pull from your registry docker pull mcp-gateway:latest
   • If you build locally from source (requires Rust and cargo in your CI environment): git clone https://github.com/MikkoParkkola/mcp-gateway.git cd mcp-gateway cargo build --release

     Optionally tag: docker build -t mcp-gateway:local .

3. Run the gateway

   • With a prebuilt image: docker run -p 39400:39400 -i mcp-gateway:latest
   • If you built locally and have a binary: ./target/release/mcp-gateway --port 39400

4. Optional: configure capabilities

   • Create a capabilities directory structure (e.g., capabilities/stock_quote.yaml)
   • Example YAML capabilities can be dropped into the directory for hot-reload
   • For OpenAPI-based imports, run the provided CLI commands to generate capabilities (examples in the README): mcp-gateway cap import stripe-openapi.yaml --output capabilities/ --prefix stripe

5. Verify installation

   • Visit http://localhost:39400/health (or your configured health endpoint) to confirm the gateway is running
   • Use your MCP client to perform a gateway_search_tools call followed by a gateway_invoke call to exercise a meta-tool and its downstream capability

Notes:

• You can swap in a different deployment method (e.g., Kubernetes) once the container image is available in your registry.
• Ensure you have capability definitions ready; starter capabilities ship with the gateway and can be extended via hot-reload.

Tips and common issues:

• Hot-reload latency: YAML-based capabilities update in ~500ms; REST OpenAPI imports are generated and available quickly, but ensure your OpenAPI spec is valid.
• Backends: The gateway abstracts away the underlying MCP servers (stdio, HTTP, SSE). If a backend misbehaves, the gateway’s circuit breaker will isolate it after a few errors.
• Environment variables: GATEWAY_PORT can be changed if you need the gateway to listen on a non-default port; LOG_LEVEL controls verbosity for troubleshooting.
• Capabilities directory: Keep capabilities modular. Use prefixes to organize capabilities by domain (e.g., stock, weather, news) and leverage hot reload to test changes without restarting the AI session.
• OpenAPI imports: When importing REST APIs from OpenAPI specs, the gateway will generate per-endpoint capabilities ready for discovery and invocation.