Configuration Reference

Both binaries are configured via YAML config files. Pass the config file path with the --config flag:

mitrity-gateway --config /etc/mitrity/mitrity-gateway.yaml
mitrity-mcp-sidecar --config /path/to/mitrity-mcp-sidecar.yaml

This reference covers all configuration fields for both binaries.

Mitrity Gateway Fields

Mitrity Gateway is configured via mitrity-gateway.yaml.

Core

Upstreams

Define the MCP servers that the gateway aggregates tools from.

upstreams:
  - name: "filesystem"
    command: "/usr/local/bin/mcp-filesystem"
    args: ["--root", "/data"]
  - name: "database"
    command: "/usr/local/bin/mcp-postgres"
    args: ["--connection-string", "postgres://..."]

Native Tools

Define HTTP API endpoints as tools alongside MCP upstreams.

native_tools:
  - name: "get_weather"
    description: "Get current weather for a location"
    method: "GET"
    url: "https://api.weather.example.com/current"
    headers:
      Authorization: "Bearer ${WEATHER_API_KEY}"

Credentials

Credential definitions for upstream authentication. Credentials are held by the gateway and never shared with agents.

credentials:
  weather_api:
    type: "api_key"
    value: "${WEATHER_API_KEY}"
  database:
    type: "connection_string"
    value: "${DATABASE_URL}"

Governed shell (exec)

The exec block enables the gateway's first-party sandboxed shell — the shell__execute tool (action type shell:execute). The design, the policy knobs, the sandbox modes and the egress allowlist are on the Governed Shell page; this is the key reference. The block is validated at boot exactly as upstreams are: an invalid block refuses to start and mitrity-gateway doctor names the field.

Logging

Cache

Full Mitrity Gateway config example

gateway_id: "gateway-001"
api_key: "sk-..."
control_plane:
  base_url: "https://api.mitrity.com"

upstreams:
  - name: "filesystem"
    command: "/usr/local/bin/mcp-filesystem"
    args: ["--root", "/data"]
  - name: "database"
    command: "/usr/local/bin/mcp-postgres"
    args: ["--connection-string", "${DATABASE_URL}"]

native_tools:
  - name: "get_weather"
    description: "Get current weather for a location"
    method: "GET"
    url: "https://api.weather.example.com/current"
    headers:
      Authorization: "Bearer ${WEATHER_API_KEY}"

credentials:
  weather_api:
    type: "api_key"
    value: "${WEATHER_API_KEY}"

logging:
  level: "info"
  format: "json"

cache:
  profile_ttl: "5m"
  max_entries: 1000

Mitrity MCP Sidecar Fields

Mitrity MCP Sidecar is configured via mitrity-mcp-sidecar.yaml.

The sidecar launches the upstream MCP server as a child process, communicating via stdio. It intercepts tools/call JSON-RPC 2.0 requests from the MCP client, evaluates them against governance policies, and either forwards allowed calls to the upstream server or returns a JSON-RPC error for denied calls.

Full Mitrity MCP Sidecar config example

api_key: "sk-..."
control_plane:
  base_url: "https://api.mitrity.com"

upstream_command: "/usr/local/bin/some-mcp-server"
upstream_args: ["--mode", "stdio"]
agent_id: "my-agent"

logging:
  level: "info"
  format: "json"

cache:
  profile_ttl: "5m"
  max_entries: 1000

Environment Variable Overrides

Core configuration fields can be overridden via environment variables. Environment variables take precedence over values in the YAML config file.

Mitrity Gateway

Mitrity MCP Sidecar

Environment variable overrides are useful for injecting secrets in containerized deployments without writing them to the config file. Both binaries are stdio MCP servers launched by the agent's MCP client, so the variables belong on the process that spawns them — the agent's container:

docker run -it \
  -e MITRITY_GATEWAY_API_KEY=sk-your-key \
  -v /path/to/mitrity-gateway.yaml:/etc/mitrity/config.yaml \
  your-agent-image

The agent then launches mitrity-mcp-gateway --config /etc/mitrity/config.yaml from inside that container and inherits the environment. See the deployment guide for why a detached gateway container is not a supported topology.

Related Documentation

• Integration Modes -- overview of Mitrity Gateway and Mitrity MCP Sidecar
• Deployment Guide -- installation and deployment options
• Governance Coverage -- what the configured binaries govern, and what they do not
• Writing Policies -- writing governance policies