Agent MCP Gateway — Claude Code MCP server: what it does
A proxy in front of your MCP servers. Three tools load at startup instead of every tool definition, and each subagent gets access by policy.
claude mcp add --env GATEWAY_MCP_CONFIG=<GATEWAY_MCP_CONFIG> --env GATEWAY_RULES=<GATEWAY_RULES> --env GATEWAY_DEFAULT_AGENT=<GATEWAY_DEFAULT_AGENT> --env GATEWAY_DEBUG=<GATEWAY_DEBUG> --transport stdio agent-mcp-gateway -- uvx agent-mcp-gatewayWhat Agent MCP Gateway does
Every MCP server you configure normally dumps its tool definitions into the context of each agent and subagent at launch. This gateway sits in between and exposes only list_servers, get_server_tools and execute_tool. An agent asks for a server and a tool when it actually needs them.
Under the hood there is a policy engine plus a proxy. Downstream servers live in mcp.json, access rules in mcp-gateway-rules.json. Deny rules win over allow rules, and tool names can be matched with wildcards such as get_*. Audit logging, latency and error metrics, hot config reload without a restart, and OAuth support are all there. Access control only works if each agent passes its own agent_id on gateway calls; skip that and the gateway has no idea whose permissions to apply.
Start with uvx agent-mcp-gateway --init, which writes template config files into ~/.config/agent-mcp-gateway/. Then register the server in your client: for Claude that is claude mcp add agent-mcp-gateway -- uvx agent-mcp-gateway. The GATEWAY_MCP_CONFIG, GATEWAY_RULES and GATEWAY_DEFAULT_AGENT variables matter when your files sit outside the default locations. HTTP transport and health checks are still planned, so today this is a stdio gateway.
What it helps with
- free up context window space taken by tool definitions nobody uses
- give each subagent only the servers and tools it is allowed to touch
- block a specific agent from a tool with a deny rule
- change servers and rules without restarting the gateway
- trace which agent called which tool from the logs
Example prompts for the agent
- List the MCP servers I can reach through the gateway
- Find the tools on the postgres server and run a query against the users table
- Check gateway status and show me the error metrics
How to install Agent MCP Gateway
Platform CLI
claude mcp add --env GATEWAY_MCP_CONFIG=<GATEWAY_MCP_CONFIG> --env GATEWAY_RULES=<GATEWAY_RULES> --env GATEWAY_DEFAULT_AGENT=<GATEWAY_DEFAULT_AGENT> --env GATEWAY_DEBUG=<GATEWAY_DEBUG> --transport stdio agent-mcp-gateway -- uvx agent-mcp-gatewayReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agent-mcp-gateway <command>
Platform CLI
codex mcp add agent-mcp-gateway --env GATEWAY_MCP_CONFIG=<GATEWAY_MCP_CONFIG> --env GATEWAY_RULES=<GATEWAY_RULES> --env GATEWAY_DEFAULT_AGENT=<GATEWAY_DEFAULT_AGENT> --env GATEWAY_DEBUG=<GATEWAY_DEBUG> -- uvx agent-mcp-gatewayReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agent-mcp-gateway <command>
Config file
{
"mcpServers": {
"agent-mcp-gateway": {
"command": "uvx",
"args": [
"agent-mcp-gateway"
],
"env": {
"GATEWAY_MCP_CONFIG": "<GATEWAY_MCP_CONFIG>",
"GATEWAY_RULES": "<GATEWAY_RULES>",
"GATEWAY_DEFAULT_AGENT": "<GATEWAY_DEFAULT_AGENT>",
"GATEWAY_DEBUG": "<GATEWAY_DEBUG>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agent-mcp-gateway <command>
Config file
{
"servers": {
"agent-mcp-gateway": {
"type": "stdio",
"command": "uvx",
"args": [
"agent-mcp-gateway"
],
"env": {
"GATEWAY_MCP_CONFIG": "<GATEWAY_MCP_CONFIG>",
"GATEWAY_RULES": "<GATEWAY_RULES>",
"GATEWAY_DEFAULT_AGENT": "<GATEWAY_DEFAULT_AGENT>",
"GATEWAY_DEBUG": "<GATEWAY_DEBUG>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agent-mcp-gateway <command>
Platform CLI
gemini mcp add -e GATEWAY_MCP_CONFIG=<GATEWAY_MCP_CONFIG> -e GATEWAY_RULES=<GATEWAY_RULES> -e GATEWAY_DEFAULT_AGENT=<GATEWAY_DEFAULT_AGENT> -e GATEWAY_DEBUG=<GATEWAY_DEBUG> agent-mcp-gateway uvx agent-mcp-gatewayReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agent-mcp-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 Agent MCP Gateway
How do I install Agent MCP Gateway in Claude Code?
Generate the config templates with uvx agent-mcp-gateway --init, then register the server: claude mcp add agent-mcp-gateway -- uvx agent-mcp-gateway. For non-default config paths use the env variant: `claude mcp add --env GATEWAY_MCP_CONFIG=<GATEWAY_MCP_CONFIG> --env GATEWAY_RULES=<GATEWAY_RULES> --env GATEWAY_DEFAULT_AGENT=<GATEWAY_DEFAULT_AGENT> --env GATEWAY_DEBUG=<GATEWAY_DEBUG> --transport stdio agent-mcp-gateway -- uvx agent-mcp-gateway`.
What does Agent MCP Gateway do?
It aggregates several MCP servers behind one gateway and hands out access by policy. Agents pull tool definitions on demand through list_servers, get_server_tools and execute_tool instead of loading everything upfront.
Why can't my agent see a tool it needs?
Most likely the call is missing agent_id, so the gateway cannot apply permissions. Check mcp-gateway-rules.json too: an explicit deny overrides an allow.
