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.

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

[gateway]
# Port number for the HTTP server (default: 3000)
# Valid range: 1-65535
port = 3000

# API key for authentication (optional)
# When set, clients must provide this key in the Authorization header
# Format: Authorization: <api_key>
api_key = ""

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

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

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

# Directory for storing large payload files (default: /tmp/jq-payloads)
# 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"

# ============================================================================
# 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 be "docker" for stdio servers (MCP Gateway Specification Section 3.2.1)
# 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: 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.
#
# For repos="all" or repos="public" (agent has no secrecy tags):
# [servers.safeoutputs.guard_policies.write-sink]
# Accept = ["*"]
#
# For scoped repos (agent has secrecy tags matching the scope):
# [servers.safeoutputs.guard_policies.write-sink]
# Accept = ["private:myorg/api-*", "private:myorg/web-*"]
#
# 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
[servers.custom]
command = "docker"
args = [
    "run",
    "--rm",
    "-i",
    "-v", "${PWD}:/workspace:ro",                        # Mount current directory (read-only)
    "-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"
# 
# Optional: HTTP headers for authentication
# [servers.http-example.headers]
# Authorization = "Bearer token123"
# X-API-Key = "api-key-123"

# ============================================================================
# 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

# ============================================================================
# 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
#
# 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 will generate warnings in logs (helps catch typos!)
# - 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