MCP Gateway: A Comprehensive Overview of Model Context Protocol (MCP) Server Access for AI Agents

Introduction

The MCP Gateway is a critical component designed to facilitate secure and scalable interactions between AI agents operating within sandboxed environments and external Model Context Protocol (MCP) servers. Developed in collaboration with GitHub’s Agentic Workflows (GH-AW), this gateway enables seamless communication by acting as an intermediary that routes requests from AI-driven workflows to backend MCP servers while enforcing strict security policies.

This document provides a detailed breakdown of the MCP Gateway, covering its installation, configuration, architectural design, security mechanisms, and API endpoints. By understanding these components, developers can effectively integrate MCP-based workflows into their applications, ensuring secure data handling and controlled access to repositories.

---

1. Core Functionality: Bridging AI Agents with MCP Servers

The MCP Gateway serves as a bridge between GitHub Agentic Workflows (GH-AW) and MCP-compatible servers, allowing AI agents to interact with external systems while maintaining security boundaries. The primary use case is enabling AI-driven workflows to access repositories, perform operations, and securely transmit data without exposing sensitive information.

Key Features

• Sandboxed Environment Support: Enables AI agents running in isolated containers to communicate with MCP servers.
• Secure Access Control: Implements guard policies to restrict repository access based on integrity levels (e.g., contributors vs. owners).
• Multi-Mode Routing: Supports both routed and unified modes for flexible request handling.
• Secrecy Labeling: Ensures sensitive data is properly tagged before transmission, preventing unauthorized exposure.

---

2. Quick Start: Setting Up the MCP Gateway

Step 1: Pulling the Docker Image

Before deploying the gateway, users must pull the official Docker image from GitHub Container Registry (GHCR):

docker pull ghcr.io/github/gh-aw-mcpg:latest

This command fetches the latest version of the MCP Gateway container image, which includes all necessary dependencies for running the service.

Step 2: Creating a Configuration File (config.json)

A JSON configuration file is required to define how the gateway interacts with backend servers. Below is an example configuration:

{
  "gateway": {
    "apiKey": "${MCP_GATEWAY_API_KEY}"
  },
  "mcpServers": {
    "github": {
      "type": "stdio",
      "container": "ghcr.io/github/github-mcp-server:latest",
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": ""
      }
    }
  }
}

Key Components Explained

• apiKey: An API key for authentication, required to validate requests.
• mcpServers: Defines the backend MCP servers the gateway will route requests to.
• type: Specifies the transport method (stdio or HTTP).
• container: The Docker image used to run the MCP server (e.g., ghcr.io/github/github-mcp-server:latest).
• env: Environment variables for authentication (e.g., GitHub personal access tokens).

Step 3: Running the Container

The gateway is executed using Docker with several environment variables and volume mounts to ensure proper operation:

docker run --rm -i \
  -e MCP_GATEWAY_PORT=8000 \
  -e MCP_GATEWAY_DOMAIN=localhost \
  -e MCP_GATEWAY_API_KEY=your-secret-key \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /path/to/logs:/tmp/gh-aw/mcp-logs \
  -p 8000:8000 \
  ghcr.io/github/gh-aw-mcpg:latest < config.json

Required Flags

• -i: Enables stdin for passing the JSON configuration file.
• -v /var/run/docker.sock:/var/run/docker.sock: Allows Docker socket access for spawning backend MCP servers.
• -p 8000:8000: Maps the host port 8000 to the container’s port, enabling external access.

Gateway Operation Modes

1. Routed Mode (/mcp/{serverID}):

• Exposes each backend server at a dedicated endpoint (e.g., /mcp/github).
• Useful when multiple servers are configured and requests must be directed to specific ones.

1. Unified Mode (/mcp):

• Routes all requests through a single endpoint, forwarding them to any configured MCP server.
• Simplifies interactions but requires careful handling of request routing.

---

3. Guard Policies: Enforcing Security and Integrity

Guard policies are essential for controlling access to repositories and ensuring data integrity within the MCP Gateway. They define rules that determine which AI agents can interact with specific servers based on their permissions and secrecy labels.

Types of Guard Policies

A. allow-only (Source Servers)

Restricts repository access by specifying allowed repositories (repos) and minimum integrity levels (min-integrity).

Example Configuration:

"github": {
  "type": "stdio",
  "container": "ghcr.io/github/github-mcp-server:latest",
  "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "" },
  "guard-policies": {
    "allow-only": {
      "repos": ["github/gh-aw-mcpg", "github/gh-aw"],
      "min-integrity": "unapproved"
    }
  }
}

Policy Parameters

| Parameter | Description | |-----------------|-----------------------------------------------------------------------------| | repos | Defines allowed repositories (e.g., "all", "public", or specific paths). | | min-integrity | Minimum integrity level required for access (none, unapproved, approved, merged). |

Repository Access Scopes:

• "all": All repositories accessible via the token.
• "public": Only public repositories.
• "owner/repo": Exact match (e.g., github/gh-aw).
• "owner/*": All repos under a specific owner.
• "owner/prefix*": Repos matching a prefix (e.g., github/gh-*).

B. write-sink (Output Servers)

Marks servers as write-only channels that accept data from agents with matching secrecy labels.

Example Configuration:

"safeoutputs": {
  "type": "stdio",
  "container": "ghcr.io/github/safe-outputs:latest",
  "guard-policies": {
    "write-sink": {
      "accept": ["private:github/gh-aw-mcpg", "private:github/gh-aw"]
    }
  }
}

Key Mapping Rules

| allow-only.repos | write-sink.accept | |--------------------|----------------------------------------| | "all" or "public" | ["*"] | | "owner/repo" | ["private:owner/repo"] | | "owner/*" | ["private:owner"] | | "owner/prefix*" | ["private:owner/prefix*"] |

---

4. Architecture Overview

The MCP Gateway’s architecture is designed to ensure secure and scalable communication between AI agents and backend servers. Below is a visual representation of its structure:

┌─────────────────────────────────────┐
│ MCP Gateway                         │
├───────────────┬─────────────────────┤
│               │                     │
│  JSON-RPC 2.0 │                     │
│               │                     │
└──────────┬────┴─────────────────────┘
           │
┌──────────▼───────────────────────────┐
│ Client ↔ /mcp/{serverID} (Routed Mode)│
│                                      │
└─────────────────────────────────────┘
┌─────────────────────────────────────┐
│                                   │
│  ┌───────────┐       ┌─────────────┐ │
│  │ Guards   │       │ Auth (7.1)   │ │
│  └──────┬──────┘       └─────────────┘ │
│         │                                      │
│  ┌──────▼──────┐ ┌───────────────────┐        │
│  │ GitHub MCP  │ │ Safe Outputs      │        │
│  │ (stdio/Docker)│ │ (write-sink)     │        │
│  └─────────────┘ └───────────────────┘        │
└─────────────────────────────────────┘

Key Components Explained

1. MCP Gateway:

• Acts as the central hub for routing requests between AI agents and backend servers.
• Supports both routed (/mcp/{serverID}) and unified (/mcp) modes.

1. Guards (WASM-Based):

• Enforce secrecy and integrity labels to ensure data remains protected.
• Loaded from MCP_GATEWAY_WASM_GUARDS_DIR per server configuration.

1. Authentication:

• Uses API keys as defined in the MCP specification (7.1).
• Ensures only authorized agents can interact with the gateway.

1. GitHub MCP Server:

• Runs within a Docker container (ghcr.io/github/github-mcp-server:latest).
• Handles standard MCP operations via stdin/stdout or HTTP sessions.

1. Safe Outputs (Write-Sink):

• Serves as a secure channel for writing data from agents.
• Ensures sensitive information is properly tagged before transmission.

---

5. Transport and Routing Mechanisms

Transport Layer

The MCP Gateway supports two primary transport methods:

1. JSON-RPC 2.0 over stdio (Containerized):

• Default mode when running in Docker.
• Uses standard input/output streams for communication between the gateway and backend servers.

1. HTTP with Session State Preservation:

• Allows HTTP-based interactions while maintaining session context.
• Useful for applications requiring persistent connections.

Routing Strategies

• Routed Mode (/mcp/{serverID}):

• Each configured MCP server has its own endpoint (e.g., /mcp/github).

• Ideal for environments where multiple servers must be isolated.

• Unified Mode (/mcp):

• Routes all requests through a single endpoint, forwarding them to any configured server.

• Simplifies interactions but requires careful request handling.

---

6. Security Framework

Security is a cornerstone of the MCP Gateway’s design, ensuring that AI agents operate within strict boundaries while accessing repositories. Key security mechanisms include:

A. WASM-Based Guard Policies

• WebAssembly (WASM) guards enforce secrecy and integrity labels per request.
• Ensures that only authorized agents with valid permissions can interact with specific repositories.

B. API Key Authentication

• All requests are authenticated using an API key (Authorization: <key>).
• Prevents unauthorized access to the gateway.

C. Secrecy Labeling

• Sensitive data is tagged before transmission, preventing exposure in logs or intermediate storage.
• Example secrecy tags:
• private:github/gh-aw-mcpg
• public (for non-sensitive operations)

---

7. Logging and Monitoring

The MCP Gateway provides comprehensive logging to track interactions between AI agents and backend servers:

1. Per-Server Logs ({serverID}.log):

• Detailed logs for each configured MCP server.
• Helps diagnose issues related to specific repositories.

1. Unified Log File (mcp-gateway.log):

• Aggregated logs for all gateway operations.
• Useful for monitoring overall system performance.

1. Markdown Workflow Previews (gateway.md):

• Human-readable summaries of workflow interactions.
• Assists in debugging and auditing.

1. Machine-Readable JSONL File (rpc-messages.jsonl):

• Raw JSON-RPC messages for programmatic analysis.
• Supports automated monitoring and alerting.

---

8. API Endpoints

The MCP Gateway exposes several RESTful endpoints for interacting with backend servers:

| Endpoint | Method | Description | |------------------------|---------|-----------------------------------------------------------------------------| | POST /mcp/{serverID} | POST | JSON-RPC request to a specific server (routed mode). | | POST /mcp | POST | Unified routing of requests to all configured servers. | | GET /health | GET | Health check endpoint (returns "OK"). |

Supported MCP Methods

• tools/list: Lists available tools on the server.
• tools/call: Executes a specified tool method.
• Any other MCP-compatible method is forwarded as-is.

---

9. Further Reading and Documentation

For in-depth details, refer to the following resources:

| Topic | Link | |--------------------------------|---------------------------------------------------------------------| | Configuration Reference | docs/CONFIGURATION.md – Server fields, TOML/JSON formats, guard policies. | | Environment Variables | docs/ENVIRONMENTVARIABLES.md – All env vars for production/development. | | Full MCP Specification | MCP Gateway Configuration Reference – Upstream spec with validation rules. | | Guard Response Labeling | docs/GUARDRESPONSELABELING.md – How guards label responses. | | HTTP Backend Sessions | docs/HTTPBACKENDSESSIONID.md – Session ID management for HTTP transport. | | Architecture Patterns | docs/MCPSERVERARCHITECTURE_PATTERNS.md – Design patterns and compatibility. | | Security Model | docs/aw-security.md – Security architecture overview. |

---

10. Conclusion

The MCP Gateway is a robust solution for enabling secure, scalable interactions between AI agents and external repositories via the Model Context Protocol (MCP). By leveraging Docker containers, guard policies, and JSON-RPC 2.0, it ensures that sensitive data remains protected while allowing seamless communication.

Developers can customize the gateway’s behavior through configuration files, enforce strict access controls with guard policies, and monitor interactions via comprehensive logging. Whether used in routed or unified mode, the MCP Gateway provides a reliable foundation for building AI-driven workflows on GitHub Agentic Workflows.

For further exploration, refer to the official documentation linked above, ensuring compliance with security best practices and optimal performance.