mcp-gateway

MCP Gateway acts as a central hub that aggregates multiple MCP servers into a single gateway. It connects to configured upstream MCP servers, fetches their tool catalogs, and exposes a unified search, describe, and invoke interface. This gateway optimizes tool discovery by providing a centralized gateway.search capability instead of dumping all tool schemas from every server, reducing context size and cognitive load for AI clients. Clients interact with the gateway to discover tools via gateway.search, then use gateway.describe to inspect a tool and gateway.invoke (or gateway.invoke_async for long-running tasks) to execute it. Tools are addressed using the Tool ID format serverKey::toolName, for example k8s::pods_list, enabling precise routing to the appropriate upstream server.

To get started, ensure the gateway is running and accessible. Use gateway.search to find tools across all connected servers, then describe a tool to preview its schema and inputs. Finally, invoke the tool with the required arguments. If a tool is long-running, prefer gateway.invoke_async and poll with gateway.invoke_status until completion. This flow minimizes unnecessary data transfer and keeps tool usage fast and focused. The gateway supports local upstream servers via stdio and remote servers via HTTP/WebSocket, so you can connect both local development instances and cloud MCP servers through a single endpoint.

Prerequisites:

• Node.js (LTS) installed on the host where you run the gateway
• Access to the internet to install the MCP Gateway package

Installation steps:

1. Install Node.js since the gateway is Node-based. If you don’t have Node.js, download it from https://nodejs.org/ and install.

2. Run the gateway using the recommended package run command shown in the README (as an example). This uses npx to fetch and run the latest release of the MCP Gateway:

# Install and run the MCP Gateway from npm registry (via npx)
npx -y @eznix/mcp-gateway@latest

3. Alternatively, you can install a local copy and run it directly if you prefer:

npm install -g @eznix/mcp-gateway
mcp-gateway

4. Create a configuration file (config.json) describing your upstream MCP servers. Example content is shown in the gateway docs; you can place it in a path you reference when starting the gateway.

5. Start the gateway with a path to your config or rely on MCP_GATEWAY_CONFIG env var to point to your configuration file:

export MCP_GATEWAY_CONFIG=./config.json
node path/to/gateway.js

Notes:

• The gateway supports both local (stdio) and remote (HTTP/WebSocket) upstream servers; ensure network access as needed.
• If running inside Docker or a container, mount your config file and expose the gateway port as described in the Docker section of the README.

Tips and common considerations:

• The gateway reduces token usage by exposing a searchable catalog instead of sending full tool schemas for every connected MCP server.
• Tool IDs follow the format serverKey::toolName. Ensure your configuration uses consistent server keys to map to the correct upstream servers.
• For remote servers, prefer HTTP/Streamable HTTP transport for compatibility and easier debugging; WebSocket is available when needed.
• If a local upstream tool requires environment variables, use the environment substitution feature in the local server configuration (e.g., {env:VAR_NAME}) to pass values securely.
• When debugging, check gateway health at the /health endpoint if you run the Docker image or HTTP server, and review gateway logs for connection issues with upstream servers.
• You can limit the tools surfaced by the gateway by filtering in gateway.search with appropriate query parameters and server filters.