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. Start SafeOutputs HTTP server

   The SafeOutputs MCP server starts on the host machine (port 8100) via ado-aw mcp-http, exposing the safe-output tool set over HTTP.

2. Start MCPG container

   The MCPG Gateway starts as a Docker container on the host network (docker run --network host), binding to port 80 for agent connections.

3. Configure MCPG routing

   The compiler-generated mcpg-config.json 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 connects to MCPG

   The Copilot agent inside the AWF container connects to MCPG via http://host.docker.internal:80/mcp.

5. Route tool calls

   MCPG receives tool calls from the agent and routes them to the appropriate upstream server (SafeOutputs HTTP server or custom stdio MCPs).

6. Clean up

   After the agent completes, both MCPG and the SafeOutputs HTTP server are stopped (condition: always).

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. Generate MCPG configuration

   The compiler generates mcpg-config.json from the agent’s mcp-servers: front matter and writes it to $(Agent.TempDirectory)/staging/mcpg-config.json for inspection.

2. Start SafeOutputs HTTP server

   The pipeline starts ado-aw mcp-http as a background process on the host, listening on port 8100.

3. Start MCPG Gateway

   The MCPG Docker container starts on the host network with the generated config passed via stdin.

4. Execute agent

   AWF runs the agent with --enable-host-access, allowing the Copilot CLI inside AWF to connect to MCPG via HTTP at http://host.docker.internal:80/mcp.

5. Clean up services

   Both MCPG and the SafeOutputs HTTP server are stopped after the agent completes (condition: always).