Agent MCP Gateway

You set up a single MCP gateway that sits between agents and multiple downstream MCP servers, allowing on-demand tool discovery and per-agent access control. This reduces each agent’s context window to only the tools they can use while the gateway handles secure proxying and auditing.

How to use

Use the gateway to access multiple MCP servers from a single entry point. You configure downstream servers, define per-agent access rules, and then connect your MCP client to the gateway. Your agents will discover available servers and tools on demand, request specific tools, and execute them through the gateway. The gateway enforces deny-before-allow policies, isolates sessions, and logs all activity for audit and performance monitoring.

Key workflow for typical usage:

• Discover which servers you can access by calling list_servers with your agent identity.
• Request available tools from a server with get_server_tools, filtering by exact names or patterns.
• Execute a tool on a server with execute_tool, providing the server name, tool name, and arguments.
• If needed, check the gateway status in debug mode using get_gateway_status to diagnose health and policy state.

How to install

Prerequisites: you need a runtime environment for running the gateway and your MCP client. This guide uses the uvx runtime for local development and Python for the gateway server.

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

Configuration and start

Configure downstream MCP servers and per-agent access rules. The gateway reads two files: one describing the downstream servers and another describing access policies per agent.

Two example configuration blocks you will create and edit are shown here in structured form.

{
  "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 MCP server",
      "url": "https://example.com/mcp",
      "transport": "http"
    }
  }
}

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

Connect your MCP client to the gateway

Add the gateway as your MCP server in your client configuration. You can point to the gateway using a local stdio proxy or a remote HTTP-backed endpoint depending on your setup.

Example client configuration (stdio gateway):

{
  "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"
      }
    }
  }
}

Notes on usage patterns

• The gateway only loads three lightweight gateway tools at startup and discovers downstream tools on demand. This minimizes upfront token consumption and maximizes context available for your tasks.

• Policy rules are evaluated with explicit denies taking precedence over allows. Wildcards are supported for both servers and tools, enabling flexible permissions management.

Security considerations

• Use strong access control policies and audit logging to monitor gateway activity. Secure the rules file outside the project directory for production deployments.

• Debug-only tools like get_gateway_status should only be enabled in development or secured environments.

Troubleshooting

• Check configuration file paths and JSON syntax. Ensure the gateway is starting with the configured mcp.json and mcp-gateway-rules.json files.

• If a downstream server is unavailable, verify the server definition and that the endpoint URL or stdio command is reachable.

Testing and development

• Use the MCP Inspector to test list_servers, get_server_tools, and execute_tool against your gateway in a controlled environment.

• Run unit tests and integration tests to confirm policy enforcement and proxying behavior.

Architecture overview

The gateway acts as a proxy layer with an access control middleware and a policy engine. It proxies requests to downstream MCP servers, ensuring session isolation and audit logging for every operation.

Notes

This gateway design emphasizes on-demand tool discovery, per-agent access controls, and hot configuration reloads for fast iteration in development and production environments.

Available tools

list_servers

List MCP servers accessible to the calling agent based on policy rules.

get_server_tools

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

execute_tool

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

get_gateway_status

Return comprehensive gateway health and diagnostics information (debug mode only).