Configuration Reference

This reference lists every configuration field of Mitrity Gateway and Mitrity MCP Sidecar, with its type and default, and the environment variables that override the core fields.

Both binaries read a YAML config file. Pass the path of the file with the --config flag:

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

The gateway binary is mitrity-gateway in its image and in the Helm chart, and mitrity-mcp-gateway as published for download. The Deployment Guide installs the download under that name. The commands on this page work the same under either name.

Mitrity Gateway Fields

Mitrity Gateway reads its configuration from 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, next to the 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. The gateway holds the credentials and never shares them 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). This table is the key reference. The design, the policy knobs, the sandbox modes and the egress allowlist are on the Governed Shell page.

The gateway validates the block at boot, exactly as it validates upstreams. With an invalid block, the gateway 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 reads its configuration from mitrity-mcp-sidecar.yaml.

The sidecar launches the upstream MCP server as a child process and talks to it over stdio. It intercepts tools/call JSON-RPC 2.0 requests from the MCP client and evaluates them against your governance policies. It forwards allowed calls to the upstream server, and 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

You can override the core configuration fields with environment variables. An environment variable takes precedence over the value 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, which is 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 the gateway inherits the environment. The deployment guide explains why a detached gateway container is not a supported topology.

Related Documentation

• Integration Modes: an 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: how to write governance policies