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
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
gateway_id | string | Yes | -- | Unique identifier for this gateway instance. Shown in audit logs and the dashboard |
api_key | string | Yes | -- | API key from the MITRITY dashboard (Settings > API Keys) |
control_plane.base_url | string | Yes | -- | URL of the MITRITY control plane (https://api.mitrity.com) |
Upstreams
Define the MCP servers that the gateway aggregates tools from.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
upstreams[] | list | Yes | -- | List of upstream MCP server definitions |
upstreams[].name | string | Yes | -- | Human-readable name for this upstream (e.g., filesystem, database) |
upstreams[].command | string | Yes | -- | Path to the upstream MCP server binary |
upstreams[].args | list of strings | No | [] | Arguments to pass to the upstream MCP server command |
upstreams[].env | map | No | {} | Environment variables to set for the upstream process |
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.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
native_tools[] | list | No | [] | List of native HTTP API tool definitions |
native_tools[].name | string | Yes | -- | Tool name exposed to agents |
native_tools[].description | string | No | -- | Human-readable description of the tool |
native_tools[].method | string | Yes | -- | HTTP method (GET, POST, PUT, DELETE) |
native_tools[].url | string | Yes | -- | Target URL for the HTTP request |
native_tools[].headers | map | No | {} | Static headers to include with every request |
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.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
credentials | map | No | {} | Named credential definitions referenced by upstreams and native tools |
credentials:
weather_api:
type: "api_key"
value: "${WEATHER_API_KEY}"
database:
type: "connection_string"
value: "${DATABASE_URL}"
Logging
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
logging.level | string | No | info | Log verbosity: debug, info, warn, error |
logging.format | string | No | json | Log output format: json or text |
Cache
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
cache.profile_ttl | duration | No | 5m | How long to cache mission profiles locally before re-fetching from the control plane |
cache.max_entries | integer | No | 1000 | Maximum number of cached mission profiles |
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.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
sentinel_id | string | Yes | -- | Unique identifier for this sidecar instance. Shown in audit logs and the dashboard |
api_key | string | Yes | -- | API key from the MITRITY dashboard (Settings > API Keys) |
control_plane.base_url | string | Yes | -- | URL of the MITRITY control plane (https://api.mitrity.com) |
upstream_command | string | Yes | -- | Path to the upstream MCP server binary that the sidecar will wrap |
upstream_args | list of strings | No | [] | Arguments to pass to the upstream MCP server command |
agent_id | string | Yes | -- | Identifier for the agent using this sidecar. Appears in audit logs and enables per-agent governance |
logging.level | string | No | info | Log verbosity: debug, info, warn, error |
logging.format | string | No | json | Log output format: json or text |
cache.profile_ttl | duration | No | 5m | How long to cache mission profiles locally before re-fetching from the control plane |
cache.max_entries | integer | No | 1000 | Maximum number of cached mission profiles |
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
sentinel_id: "mcp-agent-001"
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
| Environment Variable | Config Field | Description |
|---|---|---|
MITRITY_GATEWAY_ID | gateway_id | Gateway instance identifier |
MITRITY_GATEWAY_API_KEY | api_key | API key for control plane authentication |
MITRITY_GATEWAY_CONTROL_PLANE_URL | control_plane.base_url | Control plane URL |
MITRITY_GATEWAY_LOG_LEVEL | logging.level | Log verbosity |
MITRITY_GATEWAY_LOG_FORMAT | logging.format | Log output format |
Mitrity MCP Sidecar
| Environment Variable | Config Field | Description |
|---|---|---|
MITRITY_MCP_ID | sentinel_id | Sidecar instance identifier |
MITRITY_MCP_API_KEY | api_key | API key for control plane authentication |
MITRITY_MCP_CONTROL_PLANE_URL | control_plane.base_url | Control plane URL |
MITRITY_MCP_LOG_LEVEL | logging.level | Log verbosity |
MITRITY_MCP_LOG_FORMAT | logging.format | Log output format |
Backward compatibility: The legacy
SENTINEL_MCP_*environment variable prefix is still supported for the sidecar. New deployments should use theMITRITY_MCP_*prefix.
Environment variable overrides are useful for injecting secrets in containerized deployments without writing them to the config file:
docker run -d \
--name mitrity-gateway \
-e MITRITY_GATEWAY_API_KEY=sk-your-key \
-v /path/to/mitrity-gateway.yaml:/etc/mitrity/config.yaml \
ghcr.io/mitrity-io/mitrity-mcp-gateway:latest
Related Documentation
- Integration Modes -- overview of Mitrity Gateway and Mitrity MCP Sidecar
- Deployment Guide -- installation and deployment options
- Policies -- writing governance policies