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_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 section.

Quick Start

1. Configure Gateway Files

After running uvx agent-mcp-gateway --init (see 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 section for detailed examples and 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 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 and .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)

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)

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

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 will be ignored until the server is added

Validation Behavior:

• Structural errors (invalid JSON, missing required fields) → Fail startup/reload
• Undefined server references → Log warnings, continue with valid rules
• Policy conflicts → Deny-before-allow precedence resolves automatically

3. OAuth Support for Downstream Servers

OAuth-protected downstream servers (Notion, GitHub) are automatically supported via auto-detection when servers return HTTP 401. The gateway uses FastMCP's OAuth support to handle authentication flows transparently - browser opens once for initial authentication, then tokens are cached for future use. See OAuth User Guide for detailed setup and troubleshooting.

OAuth Limitations:

The gateway supports OAuth servers that implement Dynamic Client Registration (RFC 7591).

• ✅ Supported: OAuth with auto-detection (e.g., Notion MCP)
• ❌ Not Supported: OAuth with pre-registered apps (e.g., GitHub OAuth flow)
• 💡 For GitHub MCP: Use Personal Access Token instead

GitHub MCP with PAT Example:

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PAT}"
      }
    }
  }
}

For detailed OAuth setup and troubleshooting, see OAuth User Guide.

4. Environment Variables Reference

Variable	Description	Default	Example
GATEWAY_MCP_CONFIG	Path to MCP servers configuration file	.mcp.json, fallback: ./config/.mcp.json	export GATEWAY_MCP_CONFIG=./custom.json
GATEWAY_RULES	Path to gateway rules configuration file	.mcp-gateway-rules.json, fallback: ./config/.mcp-gateway-rules.json	export GATEWAY_RULES=~/.claude/rules.json
GATEWAY_DEFAULT_AGENT	Default agent identity when agent_id not provided (optional)	None	export GATEWAY_DEFAULT_AGENT=developer
GATEWAY_DEBUG	Enable debug mode to expose get_gateway_status tool	false	export GATEWAY_DEBUG=true
GATEWAY_AUDIT_LOG	Path to audit log file	~/.cache/agent-mcp-gateway/logs/audit.jsonl	export GATEWAY_AUDIT_LOG=./audit.jsonl
GATEWAY_TRANSPORT	Transport protocol (stdio or http)	stdio	export GATEWAY_TRANSPORT=stdio
GATEWAY_INIT_STRATEGY	Initialization strategy (eager or lazy)	eager	export GATEWAY_INIT_STRATEGY=eager

Note on GUI Applications: macOS GUI applications (Claude Desktop, etc.) run in isolated environments without access to shell environment variables. If using ${VAR_NAME} syntax in .mcp.json, add required API keys to the gateway's env object in your MCP client configuration.

Usage

The gateway runs automatically when your MCP client starts. See Quick Start for adding it to your MCP client configuration.

Custom configuration paths can be specified via environment variables in your MCP client config:

{
  "mcpServers": {
    "agent-mcp-gateway": {
      "command": "uvx",
      "args": ["agent-mcp-gateway"],
      "env": {
        "GATEWAY_MCP_CONFIG": "/path/to/custom-mcp.json",
        "GATEWAY_RULES": "/path/to/custom-rules.json"
      }
    }
  }
}

See Environment Variables Reference for all available options.

Startup Output

Loading MCP server configuration from: .mcp.json
Loading gateway rules from: .mcp-gateway-rules.json
Audit log will be written to: ~/.cache/agent-mcp-gateway/logs/audit.jsonl

Initializing proxy connections to downstream servers...
  - 2 proxy client(s) initialized
    * brave-search: ready
    * postgres: ready
  - Metrics collector initialized
  - Access control middleware registered

Agent MCP Gateway initialized successfully
  - 2 MCP server(s) configured
  - 3 agent(s) configured
  - Default policy: deny unknown agents
  - 3 gateway tools available: list_servers, get_server_tools, execute_tool
  (4 tools if GATEWAY_DEBUG=true: includes get_gateway_status)

Gateway is ready. Running with stdio transport...

Gateway Tools

The gateway exposes exactly 3 tools to agents. All tools accept an optional agent_id parameter for access control. When agent_id is not provided, the gateway uses a fallback chain to determine agent identity (see Agent Identity Modes).

For Agent Developers: To configure your agents to properly use these gateway tools with access control, see Configure Your Agents.

1. list_servers

Lists MCP servers available to the calling agent based on policy rules.

Parameters:

• agent_id (string, optional) - Identifier of the agent making the request (see Agent Identity Modes)
• include_metadata (boolean, optional) - Include technical details like transport, command, and url (default: false)

Returns:

[
  {
    "name": "brave-search",
    "description": "Web search via Brave Search API"
  },
  {
    "name": "postgres",
    "description": "PostgreSQL database access and query execution"
  }
]

With include_metadata=true:

[
  {
    "name": "brave-search",
    "description": "Web search via Brave Search API",
    "transport": "stdio",
    "command": "npx"
  },
  {
    "name": "postgres",
    "description": "PostgreSQL database access and query execution",
    "transport": "stdio",
    "command": "uvx"
  }
]

Note: Server descriptions are always included (when configured in .mcp.json) to help agents understand what each server provides. The include_metadata flag only controls whether technical details (transport, command, url) are included.

Example:

# Basic usage - returns names and descriptions
result = await client.call_tool("list_servers", {
    "agent_id": "researcher"
})

# With technical metadata
result = await client.call_tool("list_servers", {
    "agent_id": "researcher",
    "include_metadata": True
})

2. get_server_tools

Retrieves tool definitions from a specific MCP server, filtered by agent permissions.

Parameters:

• agent_id (string, optional) - Identifier of the agent (see Agent Identity Modes)
• server (string, required) - Name of the downstream MCP server
• names (string, optional) - Comma-separated list of tool names (e.g., "tool1,tool2,tool3") or single tool name
• pattern (string, optional) - Wildcard pattern for tool names (e.g., "get_*")
• max_schema_tokens (integer, optional) - Token budget limit for schemas

Returns:

{
  "tools": [
    {
      "name": "brave_web_search",
      "description": "Search the web using Brave Search",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {"type": "string"}
        },
        "required": ["query"]
      }
    }
  ],
  "server": "brave-search",
  "total_available": 5,
  "returned": 1,
  "tokens_used": 150
}

Example:

# Get all allowed tools
tools = await client.call_tool("get_server_tools", {
    "agent_id": "researcher",
    "server": "brave-search"
})

# Get specific tools by name (comma-separated)
tools = await client.call_tool("get_server_tools", {
    "agent_id": "researcher",
    "server": "brave-search",
    "names": "brave_web_search,brave_local_search"
})

# Get specific tools by pattern
tools = await client.call_tool("get_server_tools", {
    "agent_id": "backend",
    "server": "postgres",
    "pattern": "get_*"
})

# Limit token usage
tools = await client.call_tool("get_server_tools", {
    "agent_id": "researcher",
    "server": "brave-search",
    "max_schema_tokens": 1000
})

3. execute_tool

Executes a tool on a downstream MCP server with transparent result forwarding.

Parameters:

• agent_id (string, optional) - Identifier of the agent (see Agent Identity Modes)
• server (string, required) - Name of the downstream MCP server
• tool (string, required) - Name of the tool to execute
• args (object, required) - Arguments to pass to the tool
• timeout_ms (integer, optional) - Timeout in milliseconds

Returns:

{
  "content": [
    {
      "type": "text",
      "text": "Search results: ..."
    }
  ],
  "isError": false
}

Example:

# Execute a tool
result = await client.call_tool("execute_tool", {
    "agent_id": "researcher",
    "server": "brave-search",
    "tool": "brave_web_search",
    "args": {
        "query": "FastMCP documentation"
    }
})

# With timeout
result = await client.call_tool("execute_tool", {
    "agent_id": "backend",
    "server": "postgres",
    "tool": "query",
    "args": {
        "sql": "SELECT * FROM users LIMIT 10"
    },
    "timeout_ms": 5000
})

4. get_gateway_status (Debug Mode Only)

Returns comprehensive gateway health and diagnostics information.

Important: This tool is only available when debug mode is enabled (via GATEWAY_DEBUG=true environment variable or --debug CLI flag). See Security Considerations for details.

Parameters:

• agent_id (string, optional) - Identifier of the agent (see Agent Identity Modes)

Returns:

{
  "reload_status": {
    "mcp_config": {
      "last_attempt": "2025-10-30T10:30:00Z",
      "last_success": "2025-10-30T10:30:00Z",
      "last_error": null,
      "attempt_count": 1,
      "success_count": 1
    },
    "gateway_rules": {
      "last_attempt": "2025-10-30T10:35:00Z",
      "last_success": "2025-10-30T10:35:00Z",
      "last_error": null,
      "attempt_count": 2,
      "success_count": 2,
      "last_warnings": []
    }
  },
  "policy_state": {
    "total_agents": 3,
    "agent_ids": ["researcher", "backend", "admin"],
    "defaults": {"deny_on_missing_agent": true}
  },
  "available_servers": ["brave-search", "postgres"],
  "config_paths": {
    "mcp_config": "/path/to/.mcp.json",
    "gateway_rules": "/path/to/.mcp-gateway-rules.json"
  },
  "message": "Gateway is operational. Check reload_status for hot reload health."
}

Example:

# Check gateway health and reload status (requires GATEWAY_DEBUG=true)
status = await client.call_tool("get_gateway_status", {
    "agent_id": "admin"
})

# Verify last reload was successful
if status["reload_status"]["gateway_rules"]["last_error"]:
    print("Warning: Last rule reload failed!")

Error Handling

All tools return structured errors with clear messages:

{
  "error": {
    "code": "DENIED_BY_POLICY",
    "message": "Agent 'frontend' denied access to tool 'drop_table'",
    "rule": "agents.frontend.deny.tools.postgres[0]"
  }
}

Error Codes:

• DENIED_BY_POLICY - Agent lacks permission
• SERVER_UNAVAILABLE - Downstream server unreachable
• TOOL_NOT_FOUND - Requested tool doesn't exist
• TIMEOUT - Operation exceeded time limit
• INVALID_AGENT_ID - Missing or unknown agent identifier
• FALLBACK_AGENT_NOT_IN_RULES - Configured fallback agent not found in gateway rules
• NO_FALLBACK_CONFIGURED - No agent_id provided and no fallback agent configured

Complete Workflow Example

Here's a minimal working example showing the typical gateway workflow:

from fastmcp import Client

async def gateway_workflow():
    async with Client('agent-mcp-gateway') as client:
        # 1. Discover available servers
        servers = await client.call_tool('list_servers', {
            'agent_id': 'researcher'
        })
        # Response: [{"name": "brave-search", "description": "Web search..."}]

        # 2. Get tools from specific server
        tools = await client.call_tool('get_server_tools', {
            'agent_id': 'researcher',
            'server': 'brave-search'
        })
        # Response: {"tools": [...], "server": "brave-search", ...}

        # 3. Execute a tool
        result = await client.call_tool('execute_tool', {
            'agent_id': 'researcher',
            'server': 'brave-search',
            'tool': 'brave_web_search',
            'args': {'query': 'MCP protocol documentation'}
        })
        # Response: {"content": [...search results...], "isError": false}

This workflow demonstrates on-demand tool discovery - load definitions only when needed, not upfront.

Agent Identity Modes

The gateway supports two deployment modes for handling agent identity:

Multi-Agent Mode (Recommended)

Use when different agents need different permissions (production, multi-agent systems):

{
  "agents": {
    "researcher": {"allow": {"servers": ["brave-search"]}},
    "backend": {"allow": {"servers": ["postgres"]}}
  },
  "defaults": {
    "deny_on_missing_agent": true  // Require explicit agent_id
  }
}

Configure each agent to pass their identity (see Configure Your Agents).

Single-Agent Mode

Use when all agents should have the same permissions (development, personal use, single-agent deployments):

# Set default agent via environment variable
export GATEWAY_DEFAULT_AGENT=developer

Or define a "default" agent in rules:

{
  "agents": {
    "default": {
      "allow": {"servers": ["brave-search", "postgres"]}
    }
  },
  "defaults": {
    "deny_on_missing_agent": false
  }
}

Agents can omit agent_id in tool calls - the gateway automatically uses the configured default.

Technical Details: Agent Identity Resolution

When agent_id is not provided, the gateway uses this fallback chain:

1. GATEWAY_DEFAULT_AGENT environment variable (highest priority)
2. Agent named "default" in .mcp-gateway-rules.json
3. Error if neither configured

The deny_on_missing_agent setting controls this behavior:

• true: Require explicit agent_id (bypass fallback chain)
• false: Use fallback chain when agent_id omitted

Security Note: The fallback mechanism follows the principle of least privilege - it never grants implicit "allow all" access, only the explicitly configured agent's permissions.

Security Considerations

Rules File Location: Store .mcp-gateway-rules.json in-project for context optimization only. For production access control, store outside project directory (e.g., ~/.claude/mcp-gateway-rules.json) to prevent agents from reading/modifying permissions.

Debug Mode: The get_gateway_status tool exposes gateway internals and is only available when GATEWAY_DEBUG=true. Disable in production environments.

For comprehensive security guidance: See Security Guide for detailed information on rules file security, debug mode considerations, agent impersonation risks, and production best practices.

Troubleshooting

Gateway Won't Start

Symptom: Error on startup or gateway fails to initialize

Solutions:

• Check configuration files exist: Verify .mcp.json and .mcp-gateway-rules.json are in the expected location
• Validate JSON syntax: Use python -m json.tool < .mcp.json to check for syntax errors
• Check Python version: Ensure Python 3.12+ is installed (python --version)
• Verify dependencies: Run uv sync to ensure all packages are installed

Can't Connect to Downstream Server

Symptom: SERVER_UNAVAILABLE error when calling tools

Solutions:

• Verify server configuration: Check server is properly defined in .mcp.json
• Test stdio servers: Ensure command is available (npx --version, uvx --version)
• Check environment variables: Verify API keys and credentials are set
• Test HTTP servers: Try accessing server URL directly in browser
• Review startup logs: Look for server initialization errors in gateway output

Permission Denied Errors

Symptom: DENIED_BY_POLICY when agent tries to use a tool

Solutions:

• Verify agent_id: Ensure agent is passing correct identity (check audit logs)
• Check agent rules: Confirm agent exists in .mcp-gateway-rules.json
• Review policy precedence: Remember deny rules take precedence over allow rules
• Test with wildcard: Try "tools": {"server-name": ["*"]} to grant broad access temporarily
• Enable debug mode: Use GATEWAY_DEBUG=true and call get_gateway_status to inspect policy state

OAuth Authentication Issues

Symptom: Browser doesn't open or OAuth flow fails

See detailed troubleshooting in OAuth User Guide.

Quick fixes:

• Clear token cache: rm -rf ~/.fastmcp/oauth-mcp-client-cache/
• Test browser: python -m webbrowser https://example.com
• Check server URL: Verify correct OAuth server URL in .mcp.json

Hot Reload Not Working

Symptom: Changes to config files don't take effect

Solutions:

• Check file watch: Ensure config files are in expected locations
• Review logs: Look for reload errors in gateway output
• Manual reload: Send SIGHUP signal or restart gateway
• Debug mode: Use get_gateway_status to check last reload timestamps

For additional help: See Security Guide, OAuth User Guide, or open a GitHub issue.

Testing

Testing with MCP Inspector

The MCP Inspector is an interactive tool for testing MCP servers.

# Basic usage
npx @modelcontextprotocol/inspector uvx agent-mcp-gateway

# With custom config paths
GATEWAY_MCP_CONFIG=~/.config/agent-mcp-gateway/.mcp.json \
GATEWAY_RULES=~/.config/agent-mcp-gateway/.mcp-gateway-rules.json \
GATEWAY_DEFAULT_AGENT=researcher \
npx @modelcontextprotocol/inspector uvx agent-mcp-gateway

# With debug mode
GATEWAY_DEBUG=true npx @modelcontextprotocol/inspector uvx agent-mcp-gateway

Inspector features:

• View all gateway tools with schemas
• Test tools with custom inputs
• Inspect request/response messages
• Monitor logs and notifications

Testing Gateway Tools in Inspector

1. Test list_servers:

{
  "agent_id": "researcher"
}

Expected: List of servers the "researcher" agent can access.

2. Test get_server_tools:

{
  "agent_id": "researcher",
  "server": "brave-search"
}

Expected: Tool definitions from brave-search server.

3. Test execute_tool:

{
  "agent_id": "researcher",
  "server": "brave-search",
  "tool": "brave_web_search",
  "args": {
    "query": "test query"
  }
}

Expected: Search results from Brave (if server configured and running).

Troubleshooting:

• Check Logs pane for errors
• Verify agent_id exists in rules file
• Confirm downstream servers configured
• Review Message pane for policy denials

Development

Local Installation

Clone and install in development mode:

# Clone repository
git clone https://github.com/roddutra/agent-mcp-gateway.git
cd agent-mcp-gateway

# Install dependencies
uv sync

# Create local config files from examples
cp config/.mcp.json.example .mcp.json
cp config/.mcp-gateway-rules.json.example .mcp-gateway-rules.json

# Run locally
uv run python main.py --help

Add Local Gateway to MCP Client

# Claude Code CLI
claude mcp add agent-mcp-gateway \
  uv run --directory /path/to/agent-mcp-gateway python main.py

# Or manual configuration
{
  "mcpServers": {
    "agent-mcp-gateway": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/agent-mcp-gateway", "python", "main.py"],
      "env": {
        "GATEWAY_DEFAULT_AGENT": "developer"
      }
    }
  }
}

Note: The --directory flag tells uv run to change to the project directory before running, ensuring it finds pyproject.toml and the gateway configuration files.

Project Structure

agent-mcp-gateway/
├── src/                          # Core gateway implementation
├── tests/                        # Test suite
├── config/                       # Configuration examples
├── docs/                         # Documentation and specifications
├── main.py                       # Entry point
└── pyproject.toml                # Python dependencies

Running in Development

# Run locally
uv run python main.py

# With debug mode
uv run python main.py --debug

Testing

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src --cov-report=term

# Run specific test file
uv run pytest tests/test_gateway.py -v

# Run tests in watch mode
uv run pytest-watch

# Generate HTML coverage report
uv run pytest --cov=src --cov-report=html
open htmlcov/index.html

Testing with MCP Inspector:

# Basic usage (uses local config files)
npx @modelcontextprotocol/inspector uv run python main.py

# With debug mode
npx @modelcontextprotocol/inspector uv run python main.py --debug

# With custom config paths
GATEWAY_MCP_CONFIG=.mcp.json \
GATEWAY_RULES=.mcp-gateway-rules.json \
GATEWAY_DEFAULT_AGENT=researcher \
npx @modelcontextprotocol/inspector uv run python main.py

Manual testing with FastMCP Client:

uv run python -c "
import asyncio
from fastmcp import Client

async def test():
    async with Client('main.py') as client:
        result = await client.call_tool('list_servers', {'agent_id': 'researcher'})
        print(result)

asyncio.run(test())
"

Adding a New Feature

1. Update specs: Document in relevant milestone file
2. Write tests first: Create test file in tests/
3. Implement feature: Add code in src/
4. Run tests: uv run pytest
5. Check coverage: uv run pytest --cov=src
6. Update docs: Document in README and relevant files
7. Commit: Follow commit message format

Code Style

• Follow existing patterns in M0/M1 code
• Use type hints throughout
• Write docstrings for all public functions
• Keep functions focused and testable
• Add tests for all new functionality

Architecture

Component Diagram

┌─────────────────────────────────────────────────────────┐
│                    Agent / Client                       │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────┐
│              Agent MCP Gateway                          │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Gateway Tools (3 tools, ~2k tokens)             │  │
│  │  • list_servers                                   │  │
│  │  • get_server_tools                               │  │
│  │  • execute_tool                                   │  │
│  └───────────────────────────────────────────────────┘  │
│                      │                                  │
│  ┌─────────────────────────────────────────────────┐    │
│  │  AgentAccessControl Middleware                  │    │
│  │  • Extract agent_id                             │    │
│  │  • Validate permissions                         │    │
│  └─────────────────────────────────────────────────┘    │
│                      │                                  │
│  ┌─────────────────────────────────────────────────┐    │
│  │  PolicyEngine                                   │    │
│  │  • Deny-before-allow precedence                 │    │
│  │  • Wildcard matching                            │    │
│  └─────────────────────────────────────────────────┘    │
│                      │                                  │
│  ┌─────────────────────────────────────────────────┐    │
│  │  ProxyManager                                   │    │
│  │  • Session isolation                            │    │
│  │  • Connection pooling                           │    │
│  └─────────────────────────────────────────────────┘    │
│                      │                                  │
│  ┌─────────────────────────────────────────────────┐    │
│  │  AuditLogger & MetricsCollector                 │    │
│  └─────────────────────────────────────────────────┘    │
└──────────────────────┬──────────────────────────────────┘
                       │
         ┌─────────────┼─────────────┐
         ▼             ▼              ▼
   ┌─────────┐   ┌─────────┐   ┌─────────┐
   │ Server  │   │ Server  │   │ Server  │
   │   A     │   │   B     │   │   C     │
   │ (stdio) │   │ (stdio) │   │ (HTTP)  │
   └─────────┘   └─────────┘   └─────────┘

Request Flow

1. Agent sends request to gateway tool with agent_id
2. Middleware intercepts: Extracts and validates agent_id
3. Tool validates: Checks PolicyEngine for server/tool access
4. Proxy forwards: ProxyManager routes to downstream server
5. Session isolated: Each request gets fresh connection
6. Result returns: Transparently forwarded to agent
7. Audit logged: Operation recorded with metrics

Performance Characteristics

• Context reduction: 90%+ (2k tokens vs 5,000-50,000+)
• Added latency: <100ms (P95)
• Gateway overhead: <30ms per operation
• Session isolation: Automatic per-request
• Concurrent requests: Fully supported

Future Features

M2: Production (Planned)

🚧 Status: Not yet implemented

Features:

• HTTP transport for gateway server
• Health check endpoints
• Enhanced error handling
• Metrics export API
• Connection pooling optimization
• Rate limiting

When available:

# Run with HTTP transport
export GATEWAY_TRANSPORT=http
export GATEWAY_PORT=8080
uv run python main.py

# Health check endpoint
curl http://localhost:8080/health

# Metrics endpoint
curl http://localhost:8080/metrics

M3: Developer Experience (Planned)

🚧 Status: Not yet implemented

Features:

• Single-agent mode (bypass agent_id requirement)
• Config validation CLI tool
• Docker container with examples
• Interactive setup wizard
• VS Code extension

When available:

# Single-agent mode (no agent_id required)
export GATEWAY_DEFAULT_AGENT=developer
uv run python main.py

# Validate configs
uv run python -m src.cli validate

# Run with Docker
docker run -v ./config:/config agent-mcp-gateway

Documentation

• Product Requirements Document
• M0: Foundation Spec
• M0: Success Report
• M1: Core Spec
• M1: Success Report
• FastMCP Implementation Guide
• Claude Code Subagent Limitations

Contributing

Contributions welcome! Please:

1. Read the PRD and relevant milestone specs
2. Follow the existing code style and patterns
3. Write tests for all new functionality
4. Ensure all tests pass: uv run pytest
5. Update documentation as needed
6. Submit a pull request with clear description

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and questions:

• GitHub Issues: Create an issue
• Documentation: docs/
• MCP Specification: https://modelcontextprotocol.io

Acknowledgments

Built with:

• FastMCP - MCP server framework
• Model Context Protocol - Protocol specification