Deployment Guide

This guide shows you how to deploy Mitrity Gateway and Mitrity MCP Sidecar. It covers the deployment options, how to configure your agent, and recommendations for production.

Both binaries are stdio programs

Read this before you choose 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 one binds a port, serves HTTP or has a "transport URL".

In practice, this means that 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 gateway is one binary with two names. It is published as mitrity-mcp-gateway: the image ghcr.io/mitrity-io/mitrity-mcp-gateway and the raw binary mitrity-mcp-gateway-<os>-<arch>. Inside the image and in the Helm chart, it is mitrity-gateway. This page installs the raw binary as /usr/local/bin/mitrity-mcp-gateway, so its commands on a host use that name.

The macOS build exists because the gateway also serves the loopback admission API that mitrity-hook talks to. A developer who runs Claude Code on a Mac needs an edge next to it (mitrity-mcp-gateway --standalone), and the same binary serves MCP to an agent on that Mac. With ml.enabled: false (the default), the gateway never loads ONNX Runtime, so you don't have to install anything else.

The gateway handles concurrent MCP requests, tool routing, credential management and ML inference. For production workloads with many agents, give it more memory and CPU, based on the request volume you expect.

Mitrity MCP Sidecar

The sidecar ships for linux/amd64, linux/arm64, darwin/amd64, darwin/arm64 and windows/amd64. It is a lightweight stdio wrapper, with no HTTP server, no listening socket and 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

You get the binaries, images and charts from GitHub Packages. Everything below is public and signed with cosign.

• 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

The 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 and install the binary:

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 that the rest of these docs use. On Windows, move mitrity-mcp-sidecar-windows-amd64.exe to a directory in your PATH.

You pull the gateway the same way, from ghcr.io/mitrity-io/binaries/mitrity-mcp-gateway (linux/amd64, linux/arm64, darwin/amd64, darwin/arm64), and install it as /usr/local/bin/mitrity-mcp-gateway. The hook comes 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) that holds both the agent and the gateway. The agent spawns 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 that 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. It serves the loopback admission API for mitrity-hook, on a socket in a volume shared with the agent container. It governs the framework's built-in tools, not an MCP server. The chart refuses upstreams in this mode, so it cannot be mistaken for an MCP server.

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, and never privileged.

On a host

Install the binary as above and let the agent's MCP client launch it. You need nothing else: no service unit and no supervisor.

The one long-running shape that does exist is mitrity-mcp-gateway --standalone. It has no upstreams and no stdio loop. It serves 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. This one is a service in the ordinary sense, and a launchd or systemd unit is the right way to run it. It is how a developer laptop gets its built-in tools governed. To install the hook, see 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. The gateway reads end-of-file and exits. Under a restart policy, it 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"]
    }
  }
}

You need no proxy environment variables and no certificate configuration. There is also 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 the tools your agent framework has built in. See Governance Coverage.

For Mitrity MCP Sidecar

You don't need to change any environment variables. 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 one. Send an initialize request on stdin and confirm that 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, with 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 you 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), because it contains the API key.
• Use secrets management for the API key and the upstream credentials, rather than baking them into an image: a Secret on Kubernetes, Secret Manager on GCP. 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. They carry request timing, decision outcomes and upstream routing details.

Mitrity Gateway

• Set resource limits that suit 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 gives you per-agent audit trails in the MITRITY dashboard.
• Use the latest version, so that 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: an overview of Mitrity Gateway and Mitrity MCP Sidecar
• Configuration Reference: the full YAML configuration reference
• Getting Started: the end-to-end quickstart guide