Agent Mcp Gateway

Agent MCP Gateway

A Model Context Protocol (MCP) gateway that aggregates multiple MCP servers and provides policy-based access control for agents and subagents. Solves Claude Code's MCP context window waste by enabling on-demand tool discovery instead of loading all tool definitions upfront.

Status

• ✅ M0: Foundation - Configuration, policy engine, audit logging, list_servers tool
• ✅ M1: Core - Proxy infrastructure, get_server_tools, execute_tool, middleware, metrics, hot reload, OAuth support
• 🚧 M2: Production - HTTP transport, health checks (planned)
• 🚧 M3: DX - Single-agent mode, config validation CLI, Docker (planned)

Current Version: M1-Core Complete (with OAuth)

Table of Contents

• [Overview](#overview)
• [Installation](#installation)
• [Quick Start](#quick-start)
• [Command-Line Options](#command-line-options)
• [Configuration File Discovery](#configuration-file-discovery)
• [Configuration](#configuration)
• [Usage](#usage)
• [Gateway Tools](#gateway-tools)
• [Security Considerations](#security-considerations)
• [Troubleshooting](#troubleshooting)
• [Testing](#testing)
• [Development](#development)
• [Architecture](#architecture)
• [Future Features](#future-features)
• [Documentation](#documentation)
• [Contributing](#contributing)
• [License](#license)
• [Support](#support)
• [Acknowledgments](#acknowledgments)

Overview

The Problem

When multiple MCP servers are configured in development environments (Claude Code, Cursor, VS Code), all tool definitions from all servers load into every agent's and subagent's context window at startup:

• 5,000-50,000+ tokens consumed upfront
• 80-95% of loaded tools never used by individual agents
• Context needed for actual work gets wasted on unused tool definitions

The Solution

The Agent MCP Gateway acts as a single MCP server that proxies to multiple downstream MCP servers based on configurable per-agent rules:

• 3 gateway tools load at startup (~2k tokens)
• Agents discover and request specific tools on-demand
• 90%+ context reduction
• Policy-based access control per agent/subagent

How It Works

The gateway sits between agents and downstream MCP servers, exposing only 3 lightweight tools. When an agent needs specific functionality, it discovers available servers and tools through the gateway, which filters visibility based on policy rules - agents only see servers and tools they have access to. This reduces each agent's context window to only relevant tools, while the gateway handles proxying authorized requests to downstream servers.

[View detailed diagram with examples →](docs/diagram-full.png) (includes downstream servers, tools, and gateway rules examples)

Key Features

• ✅ On-Demand Tool Discovery - Load tool definitions only when needed
• ✅ Per-Agent Access Control - Configure which servers/tools each agent can access
• ✅ Easy Agent Integration - Simple template to add gateway support to any agent ([see guide](#3-configure-your-agents))
• ✅ Deny-Before-Allow Policies - Explicit deny rules take precedence
• ✅ Wildcard Support - Pattern matching for tool names (get_*, *_user)
• ✅ Session Isolation - Concurrent requests don't interfere
• ✅ Transparent Proxying - Downstream servers unaware of gateway
• ✅ Audit Logging - All operations logged for monitoring
• ✅ Performance Metrics - Track latency and error rates per agent/operation
• ✅ Hot Configuration Reload - Update rules/servers without restart
• ✅ Thread-Safe Operations - Safe concurrent access during reloads
• ✅ Diagnostic Tools - Health monitoring via get_gateway_status (debug mode only)

Installation

# Creates ~/.config/agent-mcp-gateway/ with template configuration files
uvx agent-mcp-gateway --init

This generates two template files ready to customize:

• mcp.json - Your downstream MCP servers (Brave, Postgres, etc.)
• mcp-gateway-rules.json - Per-agent access policies (who can use which servers/tools)

For local development: See [Development](#development) section.

Quick Start

1. Configure Gateway Files

After running uvx agent-mcp-gateway --init (see [Installation](#installation)), edit the generated template files:

# Define your downstream MCP servers
nano ~/.config/agent-mcp-gateway/.mcp.json

# Define agent access policies
nano ~/.config/agent-mcp-gateway/.mcp-gateway-rules.json

See [Configuration](#configuration) section for detailed examples and [Configuration File Discovery](#configuration-file-discovery) for alternative file locations.

2. Add Gateway to Your MCP Client

Claude Code CLI:

claude mcp add agent-mcp-gateway uvx agent-mcp-gateway

Manual configuration:

{
  "mcpServers": {
    "agent-mcp-gateway": {
      "command": "uvx",
      "args": ["agent-mcp-gateway"],
      "env": {
        "GATEWAY_MCP_CONFIG": "~/.config/agent-mcp-gateway/.mcp.json",
        "GATEWAY_RULES": "~/.config/agent-mcp-gateway/.mcp-gateway-rules.json",
        "GATEWAY_DEFAULT_AGENT": "developer"
      }
    }
  }
}

Note: The env variables are optional if using default config locations. See [Environment Variables Reference](#4-environment-variables-reference) for all options.

3. Configure Your Agents

The gateway's tool descriptions are self-documenting, but for proper access control you should configure how your agents identify themselves. Choose the approach that fits your use case:

Approach 1: Multi-Agent Mode (Recommended)

For different agents with different permissions, configure each agent to pass its identity.

Add this to your agent's system prompt (e.g., CLAUDE.md, .claude/agents/agent-name.md):

## MCP Gateway Access

**Available Tools (via agent-mcp-gateway):**

You have access to MCP servers through the agent-mcp-gateway. The specific servers and tools available to you are determined by the gateway's access control rules.

**Tool Discovery Process:**

When you need to use tools from downstream MCP servers:
1. Use `agent_id: "YOUR_AGENT_NAME"` in ALL gateway tool calls for proper access control
2. Call `list_servers` to discover which servers you have access to
3. Call `get_server_tools` with the specific server name to discover available tools
4. Use `execute_tool` to invoke tools with appropriate parameters
5. If you cannot access a tool you need, immediately notify the user

**Important:** Always include `agent_id: "YOUR_AGENT_NAME"` in your gateway tool calls. This ensures proper access control and audit logging.

Replace YOUR_AGENT_NAME with your agent's identifier (e.g., "researcher", "backend", "admin").

Examples: See [.claude/agents/researcher.md](.claude/agents/researcher.md) and [.claude/agents/mcp-developer.md](.claude/agents/mcp-developer.md) for complete configuration examples.

Approach 2: Single-Agent Mode

For simpler setups where all agents should have the same permissions, or when using MCP clients without system prompt configuration (e.g., Claude Desktop), configure a default agent using either method:

Option A: Environment Variable

# Set in your MCP client configuration
export GATEWAY_DEFAULT_AGENT=developer

Note: The agent specified (e.g., "developer") must exist in your .mcp-gateway-rules.json file with appropriate permissions.

Option B: "default" Agent in Rules

{
  "agents": {
    "default": {
      "allow": {
        "servers": ["*"]
      }
    }
  },
  "defaults": {
    "deny_on_missing_agent": false
  }
}

Note: Allowing all servers ("servers": ["*"]) without specifying tool restrictions grants access to all tools on all servers.

With either approach, agents can omit agent_id in tool calls - the gateway uses your configured default agent automatically.

Command-Line Options

# Show version
agent-mcp-gateway --version

# Initialize config directory (first-time setup)
agent-mcp-gateway --init

# Enable debug mode (exposes get_gateway_status diagnostic tool)
agent-mcp-gateway --debug

# Show help
agent-mcp-gateway --help

Configuration File Discovery

The gateway searches for configuration files in this order:

MCP Server Config (.mcp.json)

1. GATEWAY_MCP_CONFIG environment variable (if set)
2. .mcp.json in current directory
3. ~/.config/agent-mcp-gateway/.mcp.json (home directory)
4. ./config/.mcp.json (fallback)

Gateway Rules (.mcp-gateway-rules.json)

1. GATEWAY_RULES environment variable (if set)
2. .mcp-gateway-rules.json in current directory
3. ~/.config/agent-mcp-gateway/.mcp-gateway-rules.json (home directory)
4. ./config/.mcp-gateway-rules.json (fallback)

Tip: Use agent-mcp-gateway --init to create the home directory configs on first run.

Configuration

The gateway requires two configuration files:

1. MCP Servers Configuration

File: mcp.json (searched in [multiple locations](#configuration-file-discovery))

Defines the downstream MCP servers the gateway will proxy to. Uses the standard MCP config format compatible with Claude Code and other coding agents:

{
  "mcpServers": {
    "brave-search": {
      "description": "Web search via Brave Search API",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    },
    "postgres": {
      "description": "PostgreSQL database access and query execution",
      "command": "uvx",
      "args": ["mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "remote-server": {
      "description": "Custom remote API integration",
      "url": "https://example.com/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

Server Descriptions (Recommended): Adding a description field to each server helps AI agents understand what each server provides and when to use it. Descriptions are always returned by list_servers, enabling agents to make informed decisions about which servers to query for tools. While optional, descriptions significantly improve agent tool discovery and decision-making.

Supported Transports:

• stdio - Local servers via npx/uvx (specified with command + args)
• http - Remote HTTP servers (specified with url)

Environment Variables:

• Use ${VAR_NAME} syntax for environment variable substitution
• Set variables before running: export BRAVE_API_KEY=your-key

Important - GUI Applications (Claude Desktop, etc.): If you use ${VAR_NAME} syntax in .mcp.json, note that macOS GUI applications run in isolated environments without access to your shell's environment variables. For Claude Desktop and similar apps, add API keys to the gateway's env object in your MCP client configuration:

{
  "mcpServers": {
    "agent-mcp-gateway": {
      "command": "uvx",
      "args": ["agent-mcp-gateway"],
      "env": {
        "BRAVE_API_KEY": "your-actual-key-here",
        "DATABASE_URL": "postgresql://...",
        "GATEWAY_DEFAULT_AGENT": "claude-desktop"
      }
    }
  }
}

(If you hardcode values directly in .mcp.json without ${VAR_NAME} syntax, this is not necessary.)

2. Gateway Rules Configuration

File: mcp-gateway-rules.json (searched in [multiple locations](#configuration-file-discovery))

Defines per-agent access policies using deny-before-allow precedence:

{
  "agents": {
    "researcher": {
      "allow": {
        "servers": ["brave-search", "context7"],
        "tools": {
          "brave-search": ["brave_web_search"]
        }
      }
    },
    "backend": {
      "allow": {
        "servers": ["postgres", "laravel-boost"],
        "tools": {
          "postgres": ["query", "list_tables", "list_schemas"],
          "laravel-boost": ["get_*", "list_*", "read_*", "database_*", "search_*"]
        }
      },
      "deny": {
        "tools": {
          "postgres": ["drop_*", "delete_*"],
          "laravel-boost": ["database_query", "tinker"]
        }
      }
    },
    "admin": {
      "allow": {
        "servers": ["*"],
        "tools": {
          "brave-search": ["brave_web_search"]
        }
      },
      "deny": {
        "servers": ["notion"],
        "tools": {
          "playwright": ["browser_type"]
        }
      }
    },
    "claude-desktop": {
      "allow": {
        "servers": ["context7", "brave-search", "notion", "playwright"]
      },
      "deny": {
        "tools": {
          "playwright": ["browser_type", "browser_close_all", "launch_*"]
        }
      }
    },
    "default": {
      "deny": {
        "servers": ["*"]
      }
    }
  },
  "defaults": {
    "deny_on_missing_agent": false
  }
}

Agent Examples Explained:

researcher - Demonstrates implicit grant + explicit allow:

• brave-search: ONLY brave_web_search tool (explicit allow narrows access)
• context7: ALL tools (implicit grant - server allowed, no tool rules specified)

backend - Demonstrates wildcard allows with deny-before-allow precedence:

• postgres: ONLY query, list_tables, list_schemas (explicit allows); deny rules serve as safety net
• laravel-boost: Wildcard allows (get_*, list_*, read_*, database_*, search_*) grant broad access, BUT database_query explicitly denied despite matching database_* wildcard (deny wins), and tinker blocked as safety measure

admin - Demonstrates server wildcard + mixed access patterns:

• notion: DENIED (server-level deny overrides wildcard server allow)
• brave-search: ONLY brave_web_search (explicit restriction on one server)
• playwright: ALL tools EXCEPT browser_type (implicit grant with explicit deny)
• All other servers: ALL tools (implicit grant - no tool rules specified)

claude-desktop - Demonstrates implicit grant with multiple deny types:

• context7, brave-search, notion: ALL tools (implicit grant)
• playwright: ALL tools EXCEPT browser_type, browser_close_all, and tools matching launch_* (implicit grant with explicit + wildcard denies)

default - Principle of least privilege:

• Used as fallback when agent_id not provided and deny_on_missing_agent is false
• Denies all servers by default; use GATEWAY_DEFAULT_AGENT environment variable to specify a different default agent

Policy Precedence Order:

1. Explicit deny rules (highest priority)
2. Wildcard deny rules
3. Explicit allow rules
4. Wildcard allow rules
5. Implicit grant (if server allowed but no tool rules specified)
6. Default policy (deny)

Implicit Grant Behavior:

• If agent has server access and no allow.tools.{server} entry, all tools from that server are implicitly granted
• allow.tools.{server} entries narrow access to specified tools only
• deny.tools.{server} entries filter out specific tools (evaluated in steps 1-2)
• Rules are server-specific and don't affect other servers

Configuration Flexibility:

• Rules can reference servers not currently in .mcp.json
• Undefined server references treated as warnings (not errors)
• Allows keeping rules for temporarily removed servers
• Hot reload applies changes immediately without restart

Wildcard Patterns:

• * - Matches everything
• get_* - Matches tools starting with "get_"
• *_user - Matches tools ending with "_user"

Agent Naming:

• Use hierarchical names: team.role (e.g., backend.database, frontend.ui)
• Alphanumeric characters, hyphens, underscores, and dots allowed
• Configure your agents to pass their identity: See [Configure Your Agents](#3-configure-your-agents)

Configuration Validation

The gateway validates configurations at startup and during hot reload. Example output:

✓ Configuration loaded from .mcp.json
⚠ Warning: Agent 'researcher' references undefined server 'unknown-server'
ℹ These rules

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [roddutra](https://github.com/roddutra)
- **Source:** [roddutra/agent-mcp-gateway](https://github.com/roddutra/agent-mcp-gateway)
- **License:** MIT

Install and usage instructions live in the source repository linked above.