Deployment Guide

This guide covers deployment options, agent configuration, and production recommendations for both Mitrity Gateway and Mitrity MCP Sidecar.

Both binaries are stdio programs

Read this before choosing a topology, because it rules some out.

Mitrity Gateway and Mitrity MCP Sidecar are both MCP servers over the stdio transport. They read newline-delimited JSON-RPC from standard input and write it to standard output. Neither binds a port, neither serves HTTP, and neither has a "transport URL".

That has one practical consequence: your agent's MCP client launches the binary as a child process, the same way it launches any other stdio MCP server. A detached, long-running gateway service that agents connect to over the network is not a supported topology -- a gateway started with no stdin attached reads end-of-file and exits immediately.

Containers are fine, and recommended: the requirement is that the binary lives in the same container or pod as the agent, so the agent can spawn it.

System Requirements

Mitrity Gateway

Mitrity Gateway ships as a Linux amd64/arm64 binary, a macOS amd64/arm64 binary and a linux/amd64, linux/arm64 container image. There is no Windows gateway build -- for an agent on a Windows host, use Mitrity MCP Sidecar.

The macOS build exists because the gateway also serves the loopback admission API that mitrity-hook talks to: a developer running Claude Code on a Mac needs an edge next to it (mitrity-gateway --standalone), and the same binary serves MCP to an agent on that Mac. With ml.enabled: false (the default) it never loads ONNX Runtime, so nothing else has to be installed.

The gateway handles concurrent MCP requests, tool routing, credential management, and ML inference. For production workloads with many agents, allocate additional memory and CPU based on expected request volume.

Mitrity MCP Sidecar

The sidecar ships for linux/amd64, linux/arm64, darwin/amd64, darwin/arm64 and windows/amd64. It is a lightweight stdio wrapper: no HTTP server, no listening socket, minimal resource requirements.

Local ML inference

Both binaries load ONNX Runtime at runtime, and only when ml.enabled is true (it is false by default). The container images bundle the library. If you run a raw binary with ML enabled, install ONNX Runtime on the host and point ml.onnx_lib_path at it.

Getting the binaries and images

GitHub Packages is the distribution channel. Everything below is public and cosign-signed. The container images and the mitrity-extauthz / mitrity-llm-gateway charts exist for v0.19.0 and later; the raw-binary OCI artifacts, the macOS gateway build, mitrity-hook and the mitrity-gateway / mitrity-mcp-sidecar charts ship from v0.20.0.

Containers: use the image tags

docker pull ghcr.io/mitrity-io/mitrity-mcp-gateway:v0.19.0
docker pull ghcr.io/mitrity-io/mitrity-mcp-sidecar:v0.19.0

Verify the image signature before you run it:

cosign verify \
  --certificate-identity-regexp '^https://github.com/mitrity-io/iag-sentinel/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ghcr.io/mitrity-io/mitrity-mcp-gateway:v0.19.0

Images are built from a distroless base with no shell, no package manager, and no unnecessary system libraries. Debug symbols are stripped, and the process runs as nonroot.

Laptops and VMs: pull the raw binary with oras

Raw binaries are published to the same GHCR namespace as signed OCI artifacts. Pull the platform you need, verify the signature, check the digest, install:

VERSION=v0.20.0

# Pull. Platforms: linux/amd64, linux/arm64, darwin/amd64,
# darwin/arm64, windows/amd64 for the sidecar and the hook;
# linux/amd64, linux/arm64, darwin/amd64 and darwin/arm64 for the gateway.
oras pull --platform darwin/arm64 \
  ghcr.io/mitrity-io/binaries/mitrity-mcp-sidecar:$VERSION

# Verify the signature
cosign verify \
  --certificate-identity-regexp '^https://github.com/mitrity-io/iag-sentinel/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ghcr.io/mitrity-io/binaries/mitrity-mcp-sidecar:$VERSION

# Check the digest against the signed checksum list
sha256sum --ignore-missing -c checksums.txt

On macOS, where sha256sum is not installed by default:

shasum -a 256 --ignore-missing -c checksums.txt

checksums.txt covers every platform of the release, so --ignore-missing is what keeps the check to the binary you actually pulled. Plain sha256sum -c checksums.txt also works, but only when you have downloaded every platform's binary into the same directory -- otherwise it reports the platforms you did not download as FAILED open or read.

Then install it:

chmod +x mitrity-mcp-sidecar-<os>-<arch>
sudo mv mitrity-mcp-sidecar-<os>-<arch> /usr/local/bin/mitrity-mcp-sidecar

oras pull names the file after its platform (for example mitrity-mcp-sidecar-darwin-arm64); the mv above gives it the name the rest of these docs use. On Windows, move mitrity-mcp-sidecar-windows-amd64.exe to a directory in your PATH.

The gateway is pulled the same way, from ghcr.io/mitrity-io/binaries/mitrity-mcp-gateway (linux/amd64, linux/arm64, darwin/amd64, darwin/arm64), and the hook from ghcr.io/mitrity-io/binaries/mitrity-hook (all five platforms).

Deploying Mitrity Gateway

Alongside a containerised agent

The supported container topology is one container (or one pod) holding both the agent and the gateway, with the agent spawning the gateway over stdio.

Copy the gateway into your agent image:

FROM ghcr.io/mitrity-io/mitrity-mcp-gateway:v0.19.0 AS gateway

FROM your-agent-base
COPY --from=gateway /mitrity-gateway /usr/local/bin/mitrity-mcp-gateway
# Only needed when ml.enabled is true
COPY --from=gateway /usr/lib/libonnxruntime.so* /usr/lib/

Then point the agent's MCP client at /usr/local/bin/mitrity-mcp-gateway as shown under Agent Configuration. Mount the config file into the container and keep it readable only by the agent's user.

On Kubernetes the same rule applies within a pod: the agent's container holds the gateway binary. A separate gateway container in the pod would have no MCP client on its stdin.

The mitrity-gateway Helm chart (oci://ghcr.io/mitrity-io/charts/mitrity-gateway, v0.20.0) renders exactly the two shapes that work. In colocated mode an init container copies the gateway into a volume the agent container mounts, the config is a ConfigMap under /etc/mitrity, and the agent's MCP client spawns /opt/mitrity/bin/mitrity-gateway. In sidecar mode a second container runs mitrity-gateway --standalone -- the loopback admission API for mitrity-hook, on a socket in a volume shared with the agent container -- which governs the framework's built-in tools and no MCP server; the chart refuses upstreams in that mode so it cannot be mistaken for one. The mitrity-mcp-sidecar chart delivers the sidecar the same way. Each chart's README states the pod shapes and the node prerequisites for the governed shell (unprivileged user namespaces; never privileged).

On a host

Install the binary as above and let the agent's MCP client launch it. Nothing else is required -- no service unit, no supervisor.

The one long-running shape that does exist is mitrity-gateway --standalone: no upstreams, no stdio loop, just the loopback admission API on a Unix socket, so that mitrity-hook can ask it before Claude Code or the Claude Agent SDK runs a built-in tool. That is a service in the ordinary sense -- a launchd or systemd unit is the right way to run it -- and it is how a developer laptop gets its built-in tools governed. Installing the hook: Governance Coverage.

Not a supported topology: a detached gateway service. docker run -d, a systemd unit with Restart=always, and a Cloud Run service all start the gateway with no MCP client on its stdin. It reads end-of-file and exits -- and under a restart policy, loops. If you have a deployment shaped this way, move the binary into the agent's container or pod instead. (--standalone is the exception by design: it never opens the stdio loop, serves only the admission API, and governs only what the hook asks about.)

Deploying Mitrity MCP Sidecar

Mitrity MCP Sidecar wraps a single upstream MCP server process on the same machine as the agent. Install it as above.

Running Mitrity MCP Sidecar

The sidecar launches the upstream MCP server itself. Point your MCP client at the sidecar instead of the upstream server:

{
  "mcpServers": {
    "filesystem": {
      "command": "mitrity-mcp-sidecar",
      "args": ["--config", "/path/to/mitrity-mcp-sidecar.yaml"]
    }
  }
}

The upstream_command and upstream_args fields in the config file tell the sidecar which MCP server to launch and wrap.

Agent Configuration

For Mitrity Gateway

Agents connect to the gateway over the MCP stdio transport. Point your MCP client at the gateway binary in its configuration:

{
  "mcpServers": {
    "mitrity-gateway": {
      "command": "/usr/local/bin/mitrity-mcp-gateway",
      "args": ["--config", "mitrity-gateway.yaml"]
    }
  }
}

No proxy environment variables and no certificate configuration are needed -- and there is no URL to configure, because the gateway is a child process, not a remote endpoint.

Pointing your MCP client at the gateway governs the tools the gateway serves. It does not govern tools your agent framework has built in -- see Governance Coverage.

For Mitrity MCP Sidecar

No environment variable changes are needed. Update your MCP client configuration to launch the sidecar as the server command, and configure the upstream server in mitrity-mcp-sidecar.yaml:

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

Verifying Installation

Both binaries speak the same protocol, so the same check works for either: send an initialize request on stdin and confirm a JSON-RPC result comes back.

echo '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}' \
  | mitrity-mcp-gateway --config /etc/mitrity/mitrity-gateway.yaml

echo '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}' \
  | mitrity-mcp-sidecar --config /path/to/mitrity-mcp-sidecar.yaml

Diagnostic logs go to stderr, so they never corrupt the protocol stream on stdout. Once the agent is running, the real confirmation is the Audit Log in the dashboard: one event per governed tool call.

Production Recommendations

Both binaries

• Make the gateway the only execution path. This is the first and most important step: expose exactly one MCP server to the agent, turn off the framework's built-in execution tools, and give the agent process no credentials of its own. An agent with a built-in shell is not governed by a gateway it never calls -- Governance Coverage has the per-framework settings and the full checklist
• Pin versions in production. Use a specific tag (ghcr.io/mitrity-io/mitrity-mcp-gateway:v0.19.0) rather than latest
• Verify signatures before install, with cosign verify and sha256sum --ignore-missing -c checksums.txt. Every image, chart, and binary is signed keylessly with Sigstore from the mitrity-io/iag-sentinel release workflow
• Store the config file with restricted permissions (chmod 600) -- it contains the API key
• Use secrets management for the API key and upstream credentials rather than baking them into an image. On Kubernetes, a Secret; on GCP, Secret Manager. Both binaries accept environment-variable overrides for the sensitive fields -- see the configuration reference
• Enable log aggregation to forward the structured JSON logs on stderr to your observability stack: request timing, decision outcomes, and upstream routing details

Mitrity Gateway

• Set resource limits appropriate to your workload. One gateway process serves one agent's MCP session, but that session may issue many concurrent tool calls
• Keep the gateway and the agent in the same container or pod. Splitting them breaks the stdio transport

Mitrity MCP Sidecar

• Set agent_id to a unique identifier for each agent instance. This enables per-agent audit trails in the MITRITY dashboard
• Use the latest version to ensure you have the most current ML model and policy engine

Related Documentation

• Governance Coverage -- what MITRITY governs, what it does not, and how to close the gap
• Integration Modes -- overview of Mitrity Gateway and Mitrity MCP Sidecar
• Configuration Reference -- full YAML configuration reference
• Getting Started -- end-to-end quickstart guide