gh-aw-mcpg/config.example.toml at main · github/gh-aw-mcpg · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
# 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.github]
# repos = ["github/gh-aw-mcpg", "github/gh-aw"]  # Exact repository patterns
# min-integrity = "reader"                       # Minimum integrity level: none, reader, writer, merged
#
# 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: 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 3: 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 4: 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
# ============================================================================

# Enable Data Information Flow Control (DIFC) security model (default: false)
# When enabled, enforces information flow control policies on tool calls
# This is an experimental feature - keep disabled for standard MCP compatibility
# enable_difc = 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