# Agent MCP Gateway

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed · ★ 41
- Author: roddutra
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/roddutra/agent-mcp-gateway
- Updated: 2025-12-02
- HTML: https://affpapa.org/en/nevibecode/mcp/agent-mcp-gateway

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `GATEWAY_MCP_CONFIG`, `GATEWAY_RULES`, `GATEWAY_DEFAULT_AGENT`, `GATEWAY_DEBUG` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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
```
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>

### Codex

**Platform CLI**
```bash
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-gateway
```
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>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

**Platform CLI**
```bash
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-gateway
```
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>

## When to use it
- 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
- 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

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md