MCP Gateway

MCP Gateway combines multiple MCP servers into a single gateway, exposing their tools through unified search, describe, and invoke interfaces while keeping the overall tool surface focused. This helps reduce context size and cognitive load for AI clients by enabling targeted tool discovery and on-demand invocation across connected MCP servers.

How to use

You connect AI clients to MCP Gateway to search for tools across all configured MCP servers. Use the gateway to locate relevant tools with a quick search, describe a chosen tool to see its full schema, and invoke it when ready. Tools are referenced using a server-specific identifier in the form serverKey::toolName.

How to install

Prerequisites: you should have a runtime capable of executing MCP gateway commands, such as Bun. You will configure MCP Gateway to connect to upstream MCP servers either remotely via HTTP/WebSocket or locally as a stdio process.

Add the gateway to your MCP client configuration in one of the following ways.

Claude Code configuration snippet, using a local stdio gateway command:

{
  "mcpServers": {
    "gateway": {
      "command": "bunx",
      "args": ["@eznix/mcp-gateway@latest"]
    }
  }
}

Additional configuration and run options

You can also configure MCP Gateway for OpenCode with a local stdio gateway command. Here is the equivalent setup expressed for a JSON config used by OpenCode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp-gateway": {
      "type": "local",
      "command": ["bunx", "@eznix/mcp-gateway@latest"]
    },
  }
}

Docker install and run

Run MCP Gateway in Docker with HTTP transport and a mounted configuration.

# Build the image
docker build -t mcp-gateway .

# Run with config mounted
docker run -p 3000:3000 \
  -v ./examples/config.json:/home/gateway/.config/mcp-gateway/config.json:ro \
  mcp-gateway

Remote server configuration

Configure remote MCP servers by using HTTP or WebSocket endpoints. Remote servers are auto-detected by protocol. For example, HTTP(S) uses Streamable HTTP, while WS(S) uses WebSocket.

{
  "gh-grep": {
    "type": "remote",
    "url": "https://mcp.grep.app"
  },
  "custom-websocket": {
    "type": "remote",
    "url": "wss://my-server.com/mcp"
  }
}

Available tools

gateway.search

Search for tools across all connected MCP servers with optional filters and limits, returning matching tools with relevance scores.

gateway.describe

Retrieve detailed information about a specific tool, including its full schema and inputs.

gateway.invoke

Execute a tool synchronously and return immediate results, with optional timeout.

gateway.invoke_async

Start an asynchronous tool execution and obtain a job ID for polling results later.

gateway.invoke_status

Check the status of an asynchronous job using the provided job ID.