mcp-gateway: Unifying AI Tool Access with Reduced Context Overhead

Introduction

mcp-gateway is a universal gateway built in Rust, designed to revolutionize how AI agents interact with a multitude of tools and services. It addresses the critical challenge of managing extensive toolsets for AI, which often leads to inflated context window costs and limitations. By consolidating unlimited Model Context Protocol (MCP) servers and REST APIs behind a single, compact endpoint, mcp-gateway presents AI agents with a streamlined meta-surface of just 14-16 tools.

This intelligent routing mechanism ensures that AI agents can dynamically discover and invoke any backend tool on demand, significantly reducing context token overhead. For instance, it can achieve approximately 89% less context-token overhead on a 100-tool stack, making tool integration scalable and cost-effective.

Installation

Getting started with mcp-gateway is straightforward. The recommended method for macOS/Linux is Homebrew, but other options are available.

Quick Start (Recommended):

Install:

brew trust --tap MikkoParkkola/tap
brew install MikkoParkkola/tap/mcp-gateway

Setup Wizard: Import existing servers and configure clients.
```
mcp-gateway setup wizard --configure-client
```
Run: Start the gateway.
```
mcp-gateway serve
```
Verify: Check the health of your setup.
```
mcp-gateway doctor
```

Other Installation Methods:

Cargo: cargo install mcp-gateway
cargo-binstall: cargo binstall mcp-gateway
Direct Binary Download: Available for Windows x64 from the latest release. Specific commands for macOS and Linux are also provided in the official README.
Docker: docker run -v $(pwd)/gateway.yaml:/config.yaml ghcr.io/mikkoparkkola/mcp-gateway:latest --config /config.yaml

Examples

mcp-gateway offers flexible ways to configure and connect your tools.

Adding Backend Servers:

You can add servers using the built-in registry or by defining them in gateway.yaml.

Using the add command:

mcp-gateway add tavily # Adds a known server
mcp-gateway add my-server -- npx -y @some/mcp-server --flag # Add an arbitrary stdio command
mcp-gateway add --url https://mcp.sentry.dev/mcp sentry # Add an HTTP server

Initializing with examples: If you have no servers yet, run mcp-gateway init --with-examples to create a working gateway.yaml with public capabilities.

Connecting AI Clients:

After running mcp-gateway serve, your AI clients can connect to the gateway. The setup export command can automatically configure many popular AI clients.

Auto-export configuration:

mcp-gateway setup export --target all # Writes, backs up, and verifies client configs

Manual JSON snippet for clients: If you prefer to configure manually, add this to your client's MCP server configuration:
```
{
  "mcpServers": {
    "gateway": {
      "type": "http",
      "url": "http://localhost:39400/mcp"
    }
  }
}
```

Why Use mcp-gateway?

mcp-gateway provides significant advantages for AI tool orchestration:

Massive Context Overhead Reduction: Achieve approximately 89% less context overhead. On a 100-tool stack, this translates to substantial token and cost savings, as the AI agent only loads tools it uses in the current turn.
Unlimited, On-Demand Tool Discovery: Break free from context limits. AI agents can search for (gateway_search_tools) and invoke (gateway_invoke) any tool from an unlimited catalog as needed, rather than loading everything upfront.
Effortless REST API Integration: Easily integrate any REST API in minutes by dropping in a YAML file or importing an OpenAPI specification. The gateway ships with over 110 built-in capabilities.
Enhanced Security: Benefit from robust security features, including a tool-poisoning validator, SHA-256 capability hash-pinning, rug-pull detection, and comprehensive coverage of the OWASP Agentic AI Top 10 risks. The entire binary is #![forbid(unsafe_code)].
Production-Grade Resilience: Built-in circuit breakers, retries with backoff, rate limiting, and health checks ensure that a single flaky backend does not compromise the entire toolchain.
Seamless Configuration Updates: Hot-reload backends and configuration in milliseconds without restarting the AI session or losing context.
Multitenant Identity Propagation: Securely propagate verified end-user identity to backends, enabling per-user access control and audit trails without storing long-lived credentials.