config.example-payload-threshold.toml

# Example MCP Gateway Configuration with Payload Size Threshold
# This demonstrates the configurable payload size threshold feature
#
# Configuration Priority (highest to lowest):
# 1. Command-line flag: --payload-size-threshold 2048
# 2. Environment variable: MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD=2048
# 3. Config file: payload_size_threshold = 2048
# 4. Default: 524288 bytes (512KB)

[gateway]
port = 3000
api_key = "your-api-key-here"

# Payload directory for storing large tool responses
# Can also be set via:
# - Flag: --payload-dir /custom/path
# - Env:  MCP_GATEWAY_PAYLOAD_DIR=/custom/path
# Default: /tmp/jq-payloads
payload_dir = "/tmp/jq-payloads"

# Payload path prefix for remapping file paths returned to clients
# When set, payloadPath uses this prefix instead of the actual filesystem path
# This allows agents in containers to access payload files via mounted volumes
#
# Can also be set via:
# - Flag: --payload-path-prefix /workspace/payloads
# - Env:  MCP_GATEWAY_PAYLOAD_PATH_PREFIX=/workspace/payloads
# Default: (empty - use actual filesystem path)
#
# Example:
#   Gateway saves to:   /tmp/jq-payloads/session123/query456/payload.json
#   Returns to client:  /workspace/payloads/session123/query456/payload.json
#   Agent mounts:       -v /tmp/jq-payloads:/workspace/payloads
# payload_path_prefix = "/workspace/payloads"

# Payload size threshold (in bytes) for storing responses to disk
# Payloads LARGER than this threshold are stored to disk and return metadata
# Payloads SMALLER than or equal to this threshold are returned inline
#
# Can also be set via:
# - Flag: --payload-size-threshold 2048
# - Env:  MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD=2048
# Default: 524288 bytes (512KB)
#
# Examples:
#   payload_size_threshold = 262144  # 256KB - more aggressive file storage
#   payload_size_threshold = 524288  # 512KB - default, balances inline vs disk storage
#   payload_size_threshold = 1048576 # 1MB - minimize disk storage for most use cases
payload_size_threshold = 524288

[servers.github]
command = "docker"
args = ["run", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "-i", "ghcr.io/github/github-mcp-server:latest"]

[servers.filesystem]
command = "docker"
args = ["run", "--rm", "-i", "ghcr.io/github/filesystem-mcp-server:latest"]

# How it works:
# 
# 1. Tool returns response data
# 2. Middleware marshals data to JSON
# 3. If JSON size <= payload_size_threshold:
#    - Return response inline (no file storage)
#    - Original data preserved
# 4. If JSON size > payload_size_threshold:
#    - Save full payload to {payload_dir}/{sessionID}/{queryID}/payload.json
#    - Return metadata response with:
#      * queryID: unique query identifier
#      * payloadPath: full path to saved file
#      * preview: first 500 characters
#      * schema: jq-inferred schema of the data
#      * originalSize: size in bytes
#      * truncated: whether preview was truncated
#
# Benefits:
# - Small responses (errors, status messages, simple data) are fast and inline
# - Large responses (file contents, lists, search results) are saved to disk
# - Clients can access full payloads via filesystem when needed
# - Reduces memory pressure and network overhead