MCP Gateway Specification | GitHub Agentic Workflows
Skip to main content MCP Gateway Specification Version : 1.18.0 Status : Draft Specification Latest Version : mcp-gateway JSON Schema : mcp-gateway-config.schema.json Editor : GitHub Agentic Workflows Team Abstract Section titled “Abstract” This specification defines the Model Context Protocol (MCP) Gateway, a transparent proxy service that enables unified HTTP access to multiple MCP servers. The gateway supports containerized MCP servers, HTTP-based MCP servers, and custom server types.
The gateway provides protocol translation, server isolation, authentication, health monitoring, and extensibility for specialized server implementations. Status of This Document Section titled “Status of This Document” This section describes the status of this document at the time of publication. This is a draft specification and may be updated, replaced, or made obsolete by other documents at any time. This document is governed by the GitHub Agentic Workflows project specifications process.
Table of Contents Section titled “Table of Contents” Introduction Conformance Architecture Configuration Protocol Behavior Server Isolation Authentication Health Monitoring Error Handling Guard Policy Compliance Testing 1. Introduction Section titled “1. Introduction” 1.1 Purpose Section titled “1.1 Purpose” The MCP Gateway serves as a protocol translation layer between MCP clients expecting HTTP-based communication and MCP servers running in containers or accessible via HTTP.
It enables: Protocol Translation : Converting between containerized stdio servers and HTTP transports Unified Access : Single HTTP endpoint for multiple MCP servers Server Isolation : Enforcing boundaries between server instances through containerization Authentication : Token-based access control Health Monitoring : Service availability endpoints The gateway requires that stdio-based MCP servers MUST be containerized.
Direct command execution (stdio+command without containerization) is NOT supported because it cannot provide the necessary isolation and portability guarantees. 1.2 Scope Section titled “1.2 Scope” This specification covers: Gateway configuration format and semantics Protocol translation behavior Server lifecycle management Authentication mechanisms Health monitoring interfaces Error handling requirements This specification does NOT cover: Model Context Protocol (MCP) core protocol semantics Individual MCP server implementations Client-side MCP implementations User interfaces or interactive features (e.g., elicitation) 1.3 Design Goals Section titled “1.3 Design Goals” The gateway MUST be designed for: Headless Operation : No user interaction required during runtime Fail-Fast Behavior : Immediate failure with diagnostic information Forward Compatibility : Graceful rejection of unknown configuration features Security : Isolation between servers and secure credential handling 2.
Conformance Section titled “2. Conformance” 2.1 Conformance Classes Section titled “2.1 Conformance Classes” A conforming MCP Gateway implementation is one that satisfies all MUST, REQUIRED, and SHALL requirements in this specification. A partially conforming MCP Gateway implementation is one that satisfies all MUST requirements but MAY lack support for optional features marked with SHOULD or MAY. 2.2 Requirements Notation Section titled “2.2 Requirements Notation” The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 .
2.3 Compliance Levels Section titled “2.3 Compliance Levels” Implementations MUST support: Level 1 (Required) : Basic proxy functionality, stdio transport, configuration parsing Level 2 (Standard) : HTTP transport, authentication, health endpoints Level 3 (Complete) : All optional features including variable expressions, timeout configuration 3. Architecture Section titled “3. Architecture” 3.1 Gateway Model Section titled “3.1 Gateway Model” ┌─────────────────────────────────────────────────────────┐ │ MCP Client │ │ (HTTP Transport) │ └──────────────────────┬──────────────────────────────────┘ │ HTTP/JSON-RPC ▼ ┌─────────────────────────────────────────────────────────┐ │ MCP Gateway │ │ ┌───────────────────────────────────────────────────┐ │ │ │ Authentication & Authorization Layer │ │ │ └───────────────────────────────────────────────────┘ │ │ ┌───────────────────────────────────────────────────┐ │ │ │ Protocol Translation Layer │ │ │ └───────────────────────────────────────────────────┘ │ │ ┌───────────────────────────────────────────────────┐ │ │ │ Server Isolation & Lifecycle Management │ │ │ └───────────────────────────────────────────────────┘ │ └──────┬──────────────┬──────────────┬───────────────────┘ │ │ │ │ stdio │ HTTP │ stdio ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ MCP │ │ MCP │ │ MCP │ │ Server │ │ Server │ │ Server │ │ 1 │ │ 2 │ │ N │ └─────────┘ └─────────┘ └─────────┘ 3.2 Transport Support Section titled “3.2 Transport Support” The gateway MUST support the following transport mechanisms: stdio (containerized) : MCP servers running in containers with standard input/output based communication HTTP : Direct HTTP-based MCP servers The gateway MUST translate all upstream transports to HTTP for client communication.
3.2.1 Containerization Requirement Section titled “3.2.1 Containerization Requirement” Stdio-based MCP servers MUST be containerized. The gateway SHALL NOT support direct command execution without containerization (stdio+command) because: Containerization provides necessary process isolation and security boundaries Containers enable reproducible environments across different deployment contexts Container images provide versioning and dependency management Containerization ensures portability and consistent behavior Direct command execution of stdio servers (e.g., command: "node server.js" without a container) is explicitly NOT SUPPORTED by this specification.
The gh-aw launcher defaults the built-in agenticworkflows and safeoutputs backend containers to the runner’s effective numeric UID and primary GID, including nonzero GIDs below 1000, with a container-local writable HOME at /tmp . Identity is applied to the backend arguments sent to mcpg, independently of the parent gateway container, across engine configuration formats. This keeps owner-only ( 0600 ) config files readable and outputs runner-owned without relaxing file permissions.
Generated safeoutputs config, tools, tools metadat
The rest of this page is on the live site.