mcp-gateway — Claude Code MCP server: what it does, how to install
Connects multiple downstream MCP servers into a single hub. It searches tools via BM25 or regex and loads schemas on demand to keep the model context window clean.
claude mcp add --env STORAGE_BACKEND=<STORAGE_BACKEND> --env REDIS_URL=<REDIS_URL> --env SERVER_CONFIG_PATH=<SERVER_CONFIG_PATH> --transport stdio rupinder2-mcp-gateway -- uvx mcp-orchestration-gatewayWhat mcp-gateway does
The gateway unites downstream MCP servers running over stdio or HTTP into one interface. Instead of dumping every tool definition directly into the model context, it provides search utilities: tool_search, discover_tools, and call_remote_tool. Finding relevant actions works through BM25 natural language ranking or Python regular expressions.
Downstream tools receive an automatic namespace formatted as server_name__tool_name. External endpoints and their authentication tokens are configured in a JSON file. Schema caching runs in memory or connects to Redis when STORAGE_BACKEND is configured. Without a valid config file path in SERVER_CONFIG_PATH, the hub starts with an empty registry.
The process runs locally via stdio or serves requests over HTTP with configurable host and port settings. Execution is handled through uvx mcp-orchestration-gateway or standard Python modules.
What it helps with
- Aggregate multiple MCP servers behind a single endpoint
- Search tool schemas on demand without bloating prompt context
- Route execution requests using namespaced tool identifiers
- Connect downstream services across stdio and HTTP transports
Example prompts for the agent
- Search for weather lookup tools using
tool_search. - Inspect available functions on
local-serverusingdiscover_tools. - Execute
api-server__fetch_datathroughcall_remote_toolwith query arguments.
How to install mcp-gateway
Platform CLI
claude mcp add --env STORAGE_BACKEND=<STORAGE_BACKEND> --env REDIS_URL=<REDIS_URL> --env SERVER_CONFIG_PATH=<SERVER_CONFIG_PATH> --transport stdio rupinder2-mcp-gateway -- uvx mcp-orchestration-gatewayReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-orchestration-gateway <command>
Platform CLI
codex mcp add rupinder2-mcp-gateway --env STORAGE_BACKEND=<STORAGE_BACKEND> --env REDIS_URL=<REDIS_URL> --env SERVER_CONFIG_PATH=<SERVER_CONFIG_PATH> -- uvx mcp-orchestration-gatewayReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-orchestration-gateway <command>
Config file
{
"mcpServers": {
"rupinder2-mcp-gateway": {
"command": "uvx",
"args": [
"mcp-orchestration-gateway"
],
"env": {
"STORAGE_BACKEND": "<STORAGE_BACKEND>",
"REDIS_URL": "<REDIS_URL>",
"SERVER_CONFIG_PATH": "<SERVER_CONFIG_PATH>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-orchestration-gateway <command>
Config file
{
"servers": {
"rupinder2-mcp-gateway": {
"type": "stdio",
"command": "uvx",
"args": [
"mcp-orchestration-gateway"
],
"env": {
"STORAGE_BACKEND": "<STORAGE_BACKEND>",
"REDIS_URL": "<REDIS_URL>",
"SERVER_CONFIG_PATH": "<SERVER_CONFIG_PATH>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-orchestration-gateway <command>
Platform CLI
gemini mcp add -e STORAGE_BACKEND=<STORAGE_BACKEND> -e REDIS_URL=<REDIS_URL> -e SERVER_CONFIG_PATH=<SERVER_CONFIG_PATH> rupinder2-mcp-gateway uvx mcp-orchestration-gatewayReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-orchestration-gateway <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-gateway
How to install mcp-gateway in Claude Code?
Run claude mcp add mcp-gateway -- uvx mcp-orchestration-gateway. To supply environment variables, run `claude mcp add --env STORAGE_BACKEND=<STORAGE_BACKEND> --env REDIS_URL=<REDIS_URL> --env SERVER_CONFIG_PATH=<SERVER_CONFIG_PATH> --transport stdio rupinder2-mcp-gateway -- uvx mcp-orchestration-gateway`.
What does mcp-gateway do?
It acts as a central hub for downstream MCP servers, aggregating their schemas behind search and deferred loading tools. This keeps the agent context window lean.
Which storage backends does mcp-gateway support?
It defaults to an in-memory backend for development. For persistent schema caching, set STORAGE_BACKEND to redis and configure the connection via REDIS_URL.
