config.example.toml

# MCP Gateway Configuration Example
# This file demonstrates all available configuration options for the MCP Gateway.
# Copy this file to config.toml and customize for your needs.
# TOML files are parsed as TOML 1.1 via BurntSushi/toml v1.6.0+, so external
# validators/editors should also support TOML 1.1 syntax.

# ============================================================================
# Gateway Configuration (Optional)
# ============================================================================
# Gateway-level settings that apply to the entire server.

[gateway]
# Note: This field is parsed and validated but does NOT control the actual listen port.
# To change the listen port, use the --listen flag: ./awmg --config config.toml --listen 127.0.0.1:4000
# This field is stored for metadata purposes only. Valid range: 1-65535
port = 3000

# Agent IDs for concurrent session isolation and optional authentication matching (optional)
# Configure either agent_id or agent_ids, but not both.
# Clients must provide a configured agent ID in the Authorization header.
agent_ids = ["primary-agent", "enclave-agent"]

# Domain name for the gateway (optional)
# Used for CORS and other domain-specific features
domain = ""

# Timeout for backend MCP server startup in seconds (default: 30)
# How long to wait for an MCP server to start before timing out
startup_timeout = 60

# Timeout for tool execution in seconds (default: 60)
# How long to wait for a tool call to complete before timing out
tool_timeout = 120

# Optional: Container runtime for stdio MCP server launches generated from JSON stdin `container` configs.
# Supported values: "docker" (default), "podman".
# Can be overridden with MCP_GATEWAY_CONTAINER_RUNTIME.
# container_runtime = "docker"

# Optional: Override container runtime executable/binary path (e.g., "/usr/bin/podman", "nerdctl")
# container_runtime_command = ""

# Note: `container_runtime_args` applies only to JSON stdin `container` conversion.
# For TOML stdio servers, put runtime-level options directly in each server's `args`.

# Directory for storing large payload files (default: /tmp/jq-payloads)
# Must be an absolute path
# Payloads are segmented by session ID: {payload_dir}/{sessionID}/{queryID}/payload.json
# Can also be set via MCP_GATEWAY_PAYLOAD_DIR environment variable or --payload-dir flag
# payload_dir = "/tmp/jq-payloads"

# Keepalive interval (seconds) for HTTP backends (default: 1500 = 25 minutes)
# Prevents remote servers from expiring idle sessions by sending periodic pings.
# Set to -1 to disable keepalive pings entirely.
# keepalive_interval = 1500

# Force repos="public" allow-only policy when the workflow repo is public (default: enabled)
# When enabled (default), the gateway reads GITHUB_REPOSITORY and calls the GitHub API at
# startup; if the repo is public, it overrides the allow-only guard policy for all servers to
# repos="public", preventing agents from reading private repository data.
# Set to false to opt out (e.g., when private-to-public-flows: allow is set in workflow front-matter).
# Can also be controlled via MCP_GATEWAY_FORCE_PUBLIC_REPOS environment variable.
# force_public_repos = true
#
# OpenTelemetry TOML key migration:
# - Prefer [gateway.opentelemetry] for new configs.
# - Legacy [gateway.tracing] is still accepted for TOML migrations.
# - If both sections are present, [gateway.opentelemetry] takes precedence.

# Multi-agent gateways require an explicit policy for each configured identity.
[gateway.agent_policies.primary-agent]
servers = ["github"]

[gateway.agent_policies.enclave-agent]
servers = ["github"]

# ============================================================================
# MCP Server Configurations
# ============================================================================
# Define one or more MCP servers that the gateway will proxy to.
# Each server requires a unique name (e.g., [servers.github], [servers.memory])

# Example 1: GitHub MCP Server (stdio via Docker)
[servers.github]
# Required: Must match configured container runtime command for stdio servers (default: "docker")
# See: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md#321-containerization-requirement
command = "docker"

# Required: Arguments for the docker command
# Standard pattern: ["run", "--rm", "-i", <env vars>, <container image>]
args = [
    "run",
    "--rm",                                              # Remove container after exit
    "-i",                                                # Interactive mode for stdin/stdout
    "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",                # Pass through env var from host
    "-e", "NO_COLOR=1",                                  # Disable color output
    "-e", "TERM=dumb",                                   # Set terminal to dumb mode
    "ghcr.io/github/github-mcp-server:latest"            # Container image
]

# Optional: Environment variables for the MCP server
# Empty string "" means pass through from host environment
# Non-empty string means set explicit value
[servers.github.env]
GITHUB_PERSONAL_ACCESS_TOKEN = ""  # Pass through from host
# DEBUG = "true"                   # Explicit value example

# Optional: Tool filtering
# tools = ["*"]                    # Allow all tools (default)
# tools = ["read_file", "list_files"]  # Allow specific tools only

# Optional: Per-tool response filters (jq expressions)
# Transforms tool response payloads before they are returned and before large-payload
# preview/schema processing runs.
# [servers.github.tool_response_filters]
# search_code = ".results[:20]"
# get_file_contents = "{path: .path, sha: .sha}"

# Optional: Guard policies for access control at the MCP gateway level
# The structure is server-specific. For GitHub MCP server, this controls repository access.
# Example: Restrict access to specific GitHub organization and repositories
# [servers.github.guard_policies.allow-only]
# repos = ["github/gh-aw-mcpg", "github/gh-aw"]  # Exact repository patterns
# min-integrity = "unapproved"                   # Minimum integrity level for GitHub changes:
#                                                #   - none: allow any ref (branches, PRs, tags)
#                                                #   - unapproved: allow open PRs even if not yet approved
#                                                #   - approved: only allow PRs that have required approvals
#                                                #   - merged: only allow merged code on the default branch
#                                                # See the README "GitHub guard policies" section for more details.
#
# Other examples:
# repos = "all"                                  # All repositories accessible by token
# repos = "public"                               # Public repositories only
# repos = ["myorg/*", "partner/shared-repo"]     # Organization wildcard and specific repo
# repos = ["myorg/api-*", "myorg/web-*"]        # Prefix matching with wildcards

# Example 2: Safe Outputs Server (write-sink for buffered updates)
# IMPORTANT: Write-sink is REQUIRED for ALL output servers when DIFC guards are
# enabled on any other server. Without it, the output server gets a noop guard
# that causes integrity violations when the agent has tags from other guards.
# [servers.safeoutputs]
# command = "docker"
# args = ["run", "--rm", "-i", "ghcr.io/github/safe-outputs:latest"]
#
# Write-sink guard policy for output servers
# The accept patterns must match the agent's secrecy tags, which depend on
# the GitHub guard's allow-only.repos configuration.
#
# CRITICAL: The gh-aw compiler MUST set sink-visibility based on the target
# repo's visibility to prevent data exfiltration (GitLost vulnerability class).
#
# For a PUBLIC target repo (blocks tainted agents):
# [servers.safeoutputs.guard_policies.write-sink]
# accept = ["*"]
# sink-visibility = "public"
#
# For a PRIVATE target repo with scoped repos:
# [servers.safeoutputs.guard_policies.write-sink]
# accept = ["private:myorg/api-*", "private:myorg/web-*"]
# sink-visibility = "private"
#
# For a PRIVATE target repo with broad access (repos="all"):
# [servers.safeoutputs.guard_policies.write-sink]
# accept = ["*"]
# sink-visibility = "private"
#
# Accept pattern format: "visibility:owner/repo-pattern"
# Visibility prefixes: private, public, internal
# Special value: "*" (wildcard) accepts writes from any agent (must be sole entry)
#
# Quick reference (see README for full table):
#   repos = "all"           → accept = ["*"]
#   repos = "public"        → accept = ["*"]
#   repos = ["org/*"]       → accept = ["private:org"]
#   repos = ["org/repo"]    → accept = ["private:org/repo"]
#   repos = ["org/prefix*"] → accept = ["private:org/prefix*"]

# Example 3: Memory MCP Server (stdio via Docker)
[servers.memory]
command = "docker"
args = [
    "run",
    "--rm",
    "-i",
    "-e", "NO_COLOR=1",
    "-e", "TERM=dumb",
    "-e", "PYTHONUNBUFFERED=1",                          # Python-specific: disable buffering
    "mcp/memory"
]

# Example 4: Custom MCP Server with Volume Mounts
# NOTE: TOML does not support ${VAR} expansion in server args/env fields.
# Use absolute paths directly in args — shell variables like ${PWD} will NOT be expanded.
# (The [gateway.opentelemetry] section supports ${VAR} expansion; [gateway.tracing] does not.)
[servers.custom]
command = "docker"
# Optional: Working directory for server process (currently parsed but not used by launcher)
# working_directory = "/workspace"
#
# Optional: Informational URI to this server entry in an MCP registry
# registry = "https://example.com/mcp-registry/servers/custom"
args = [
    "run",
    "--rm",
    "-i",
    "-v", "/absolute/path/to/workspace:/workspace:ro",   # Use an absolute path (TOML does not expand ${PWD})
    "-e", "NO_COLOR=1",
    "-e", "TERM=dumb",
    "custom/mcp-server:latest"
]

# Example 5: HTTP-based MCP Server
# [servers.http-example]
# type = "http"
# url = "https://example.com/mcp"
# connect_timeout = 45       # Optional: Per-transport connect timeout in seconds (default: 30)
# tool_timeout = 600         # Optional: Per-server tool timeout in seconds (default: gateway.tool_timeout)
# rate_limit_threshold = 3   # Optional: Consecutive rate-limit errors before circuit opens
# rate_limit_cooldown = 60   # Optional: Seconds before OPEN→HALF-OPEN probe
# registry = "https://example.com/mcp-registry/servers/http-example"
# 
# Optional: HTTP headers for authentication
# [servers.http-example.headers]
# Authorization = "Bearer token123"
# X-API-Key = "api-key-123"
#
# Optional: GitHub Actions OIDC auth for upstream HTTP server
# [servers.http-example.auth]
# type = "github-oidc"
# audience = "https://example.com/mcp"

# ============================================================================
# Advanced Options
# ============================================================================

# Guards enforcement mode: strict, filter, or propagate (default: strict)
# Guards are automatically enabled when an allow-only policy is detected
# in the server configuration (guard-policies field)
# guards_mode = "strict"

# Launch MCP servers sequentially during startup (default: parallel launch)
# Useful when servers have ordering dependencies or for debugging startup issues
# sequential_launch = false

# ============================================================================
# Security: mTLS & HMAC Request Signing
# ============================================================================
# These options are configured via CLI flags or environment variables, NOT
# directly in the TOML file. They are documented here for reference.
#
# TLS (one-way or mutual):
#   --tls-cert <path>   Path to TLS server certificate PEM file (enables HTTPS)
#                       Env: MCP_GATEWAY_TLS_CERT
#   --tls-key <path>    Path to TLS server private key PEM file (required with --tls-cert)
#                       Env: MCP_GATEWAY_TLS_KEY
#   --tls-ca <path>     Path to CA certificate PEM file for client certificate
#                       verification — enables mutual TLS (mTLS)
#                       Env: MCP_GATEWAY_CA_CERT
#
# HMAC request signing:
#   --hmac-secret <s>   Shared HMAC-SHA256 secret for request signing and replay
#                       protection. When set, requests to HMAC-protected MCP
#                       handler routes must include:
#                         X-MCP-Timestamp  — Unix-second timestamp
#                         X-MCP-Nonce      — unique per-request random nonce
#                         X-MCP-Signature  — hex-encoded HMAC-SHA256 signature
#                       Common operational endpoints such as /health and
#                       /close are intentionally not HMAC-protected.
#                       Env: MCP_GATEWAY_HMAC_SECRET
#
# Example (run command):
#   ./awmg --config config.toml \
#     --tls-cert /path/to/server.crt \
#     --tls-key  /path/to/server.key \
#     --tls-ca   /path/to/ca.crt \
#     --hmac-secret "$(openssl rand -hex 32)"

# ============================================================================
# Notes
# ============================================================================
#
# Server Types:
# - "stdio": Process-based MCP server communicating via stdin/stdout (default)
# - "http": HTTP-based MCP server (fully supported)
#
# Docker Best Practices:
# - Always use --rm to clean up containers after exit
# - Use -i for interactive mode (required for stdin/stdout communication)
# - Set NO_COLOR=1 and TERM=dumb for better compatibility
# - Use ${VAR_NAME} syntax to reference environment variables in JSON stdin and in TOML's [gateway.opentelemetry] section
# - TOML does not support ${VAR_NAME} expansion in server args/env fields; use absolute paths instead
# - The [gateway.opentelemetry] section supports ${VAR_NAME} expansion; the legacy [gateway.tracing] section does not
#
# Environment Variables:
# - Empty value ("") passes through from host environment
# - Non-empty value sets explicit value in container
# - Undefined host variables will cause startup errors
#
# Tool Filtering:
# - ["*"] allows all tools (default behavior)
# - ["tool1", "tool2"] allows only specified tools
# - Useful for security and limiting server capabilities
#
# Configuration Validation:
# - Required fields: command, args (for stdio servers)
# - Unknown keys are rejected with an error (helps catch typos at startup!)
# - Parse errors show exact line and column numbers for easy debugging
# - Example: "failed to parse TOML at line 2, column 6: expected '=' ..."
#
# Common Typos Detected:
# - prot → port
# - startup_timout → startup_timeout
# - tool_timout → tool_timeout
#
# For more information, see:
# - MCP Protocol: https://github.com/modelcontextprotocol
# - Documentation: README.md in this repository