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
• Installation
• Quick Start
• Command-Line Options
• Configuration File Discovery
• Configuration
• Usage
• Gateway Tools
• Security Considerations
• Troubleshooting
• Testing
• Development
• Architecture
• Future Features
• Documentation
• Contributing
• License
• Support
• 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 → (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)
• ✅ 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_

... View full README on GitHub