MCP Gateway (MCPG)

MCP Gateway (MCPG)

The MCP Gateway (gh-aw-mcpg) is the upstream MCP routing layer that connects agents to their configured MCP servers. It replaces the previous custom MCP firewall with the standard gh-aw gateway implementation.

Architecture

                          Host
┌─────────────────────────────────────────────────┐
│                                                 │
│  ┌──────────────┐     ┌──────────────────────┐  │
│  │ SafeOutputs  │     │  MCPG Gateway        │  │
│  │ HTTP Server  │◀────│  (Docker, --network   │  │
│  │ (ado-aw      │     │   host, port 80)     │  │
│  │  mcp-http)   │     │                      │  │
│  │ port 8100    │     │  Routes tool calls   │  │
│  └──────────────┘     │  to upstreams        │  │
│                       └──────────┬───────────┘  │
│                                  │              │
│          ┌─────────────────┐     │              │
│          │  Custom MCP     │◀────┘              │
│          │  (stdio server) │                    │
│          └─────────────────┘                    │
└─────────────────────────────────────────────────┘
                       │
          host.docker.internal:80
                       │
┌─────────────────────────────────────────────────┐
│                  AWF Container                   │
│                                                 │
│  ┌──────────┐                                   │
│  │  Copilot │──── HTTP ──── MCPG (via host)     │
│  │  Agent   │                                   │
│  └──────────┘                                   │
└─────────────────────────────────────────────────┘

How It Works

1. SafeOutputs HTTP server starts on the host (port 8100) via ado-aw mcp-http
2. MCPG container starts on the host network (docker run --network host)
3. MCPG config (generated by the compiler) defines:
   • SafeOutputs as an HTTP backend (type: "http", URL points to localhost:8100)
   • Custom MCPs as stdio servers (type: "stdio", spawned by MCPG)
   • Gateway settings (port 80, API key, payload directory)
4. Agent inside AWF connects to MCPG via http://host.docker.internal:80/mcp
5. MCPG routes tool calls to the appropriate upstream (SafeOutputs or custom MCPs)
6. After the agent completes, MCPG and SafeOutputs are stopped

MCPG Configuration Format

The compiler generates MCPG configuration JSON from the mcp-servers: front matter:

{
  "mcpServers": {
    "safeoutputs": {
      "type": "http",
      "url": "http://localhost:8100/mcp",
      "headers": {
        "Authorization": "Bearer <api-key>"
      }
    },
    "custom-tool": {
      "type": "stdio",
      "container": "node:20-slim",
      "entrypoint": "node",
      "entrypointArgs": ["server.js"],
      "tools": ["process_data", "get_status"]
    }
  },
  "gateway": {
    "port": 80,
    "domain": "host.docker.internal",
    "apiKey": "<gateway-api-key>",
    "payloadDir": "/tmp/gh-aw/mcp-payloads"
  }
}

Runtime placeholders (${SAFE_OUTPUTS_PORT}, ${SAFE_OUTPUTS_API_KEY}, ${MCP_GATEWAY_API_KEY}) are substituted by the pipeline before passing the config to MCPG.

Pipeline Integration

The MCPG is automatically configured in generated standalone pipelines:

1. Config Generation: The compiler generates mcpg-config.json from the agent’s mcp-servers: front matter
2. SafeOutputs Start: ado-aw mcp-http starts as a background process on the host
3. MCPG Start: The MCPG Docker container starts on the host network with config via stdin
4. Agent Execution: AWF runs the agent with --enable-host-access, copilot connects to MCPG via HTTP
5. Cleanup: Both MCPG and SafeOutputs are stopped after the agent completes (condition: always)

The MCPG config is written to $(Agent.TempDirectory)/staging/mcpg-config.json in its own pipeline step, making it easy to inspect and debug.