Configuration Reference

This page is the reference for every gateway setting. The binary parses its configuration with clap, so each option has both a CLI flag and an environment variable, and both feed the same Config struct. When a setting is supplied as a flag and an environment variable at the same time, the command-line flag wins.

For the always-current list, ask the binary directly:

cargo run -p contextforge-gateway-rs --bin contextforge-gateway-rs -- --help

The sections below group the options by concern: listeners, JWT, Redis, upstream transport, runtime, telemetry, and logging.

Minimum Useful Configuration

At startup, the CLI requires Redis location and Redis connection mode:

--redis-address
--redis-port
--redis-mode

To serve useful traffic, the process also needs:

If no token verification key or secret is configured, authenticated MCP requests cannot pass the claims layer.

Listener Options

--address and --tls-address may both be configured, but they must not use the same socket address.

JWT Options

The claims layer validates issuer, audience, and expiration:

The JWT sub claim selects the Redis user config key. The path virtual host id then selects one virtual host inside that config.

Redis Options

Local Compose exposes plain Redis on 127.0.0.1:6379, so local runs normally use:

--redis-address 127.0.0.1 \
--redis-port 6379 \
--redis-mode plain-text

Runtime config values are MessagePack encoded. Redis is the current transport for config, not the routing model itself.

Upstream MCP Transport Options

Connection modes:

If an upstream backend URL is http://... and the mode is omitted, calls fail before reaching that backend because the reqwest client is HTTPS-only.

Runtime Options

When runtime plugins are enabled, plugin config is read from Redis key ContextForgeGatewayRuntimePluginConfig. That key is a control-plane trust boundary because it decides which registered hooks run.

Telemetry Options

Default endpoints:

RUST_TRACE_LOG controls which spans reach the OTLP trace layer. The HTTP trace layer emits debug-level spans, so local trace verification usually needs:

RUST_TRACE_LOG=debug

Logging Options

Common Flag Sets

Local HTTP Gateway And Plain Redis

--address 127.0.0.1:8001 \
--redis-address 127.0.0.1 \
--redis-port 6379 \
--redis-mode plain-text \
--token-verification-public-key assets/jwt.key.pub \
--upstream-connection-mode plain-text-or-tls

Downstream TLS Listener

--tls-address 0.0.0.0:8443 \
--server-certificate assets/contextforgeCA/contextforge-server.cert.pem \
--server-private-key assets/contextforgeCA/contextforge-server.key.pem

You may combine this with --address to expose both HTTP and HTTPS listeners.

HMAC Token Verification

--token-verification-secret "${CONTEXTFORGE_GATEWAY_RS_TOKEN_SECRET}"

Use this only when downstream JWTs are signed with an HS* algorithm. RSA tokens need --token-verification-public-key.

Redis TLS

--redis-address 127.0.0.1 \
--redis-port 16379 \
--redis-mode tls \
--redis-tls-trust-bundle assets/contextforgeCA/contextforge.intermediate.ca-chain.cert.pem

Upstream mTLS

--upstream-connection-mode mtls-only \
--upstream-trust-bundle assets/contextforgeCA/contextforge.intermediate.ca-chain.cert.pem \
--upstream-certificate assets/contextforgeCA/contextforge-client.cert.pem \
--upstream-private-key assets/contextforgeCA/contextforge-client.key.pem

The certificate and key paths must point to PEM files accepted by reqwest.

Startup Validation

The gateway fails fast for these invalid combinations: