New: Agent approvals, red teaming and model scanning. See how
MITRITY
Docs / Getting Started / Quickstart

Quickstart

This guide gets your first AI agent governed by MITRITY in under five minutes. You register the agent, install Mitrity Gateway next to it and point the agent at the gateway. When you finish, the gateway is connected to the MITRITY control plane and streams governance events in real time.

Prerequisites

Before you begin, make sure you have:

  • A MITRITY account. If you don't have one yet, sign up here.
  • At least one AI agent running in your environment. Any framework works: LangChain, CrewAI, AutoGen, MCP or custom.
  • A 64-bit Linux or macOS host (amd64 or arm64) where the agent runs. The gateway binary ships for Linux and macOS, and the container image is Linux-only. There is no Windows gateway build: on Windows, use Mitrity MCP Sidecar instead.
  • oras and cosign to pull and verify the binary, or Docker if you prefer the container image.
  • Your Agent Key. You get it when you register an agent in the MITRITY dashboard, in Step 1.

Step 1: Create your workspace

  1. Log in to the MITRITY dashboard and go to Agents > Register Agent.
  2. Enter these values for your first agent:
    • Name: sales-bot
    • Mission scope: "Read CRM contacts, send follow-up emails, update deal stages"
  3. Under Intent Policy, select the policy that governs the agent. This field is required. If you don't have a policy yet, select Create Policy, enter a name and select Create. The new policy has allow-all, fail-open defaults.
  4. Select Register Agent.

MITRITY now generates an Agent ID and a one-time Agent Key (ak_...). Save the Agent Key now: it cannot be retrieved later. You need both values in Step 2.

Step 2: Install Mitrity Gateway

Mitrity Gateway is an MCP server that speaks stdio. Your agent's MCP client launches it as a child process and talks to it over stdin/stdout. It is not a network service that you start once and connect to, so install it where the agent runs.

  1. Create a config file, mitrity-gateway.yaml, that defines your upstream MCP servers. Put your Agent ID and Agent Key from Step 1 in agent_id and api_key:
agent_id: "your-agent-id"
api_key: "ak_your-agent-key"
control_plane:
  base_url: "https://api.mitrity.com"

upstreams:
  - name: "filesystem"
    command: "/usr/local/bin/mcp-filesystem"
    args: ["--root", "/data"]
  1. Install the gateway in one of two ways: as a standalone binary on the host, or as a container image in the agent's container or pod.

Standalone binary

Binaries are published to GitHub Packages as signed OCI artifacts. The commands below:

  1. pull the binary with oras;
  2. verify its signature with cosign;
  3. check it against checksums.txt;
  4. make it executable and move it to /usr/local/bin/mitrity-mcp-gateway.
VERSION=v0.20.0   # raw-binary artifacts ship from v0.20.0; earlier releases are images only

oras pull --platform linux/amd64 \
  ghcr.io/mitrity-io/binaries/mitrity-mcp-gateway:$VERSION

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-gateway:$VERSION

sha256sum --ignore-missing -c checksums.txt
chmod +x mitrity-mcp-gateway-linux-amd64
sudo mv mitrity-mcp-gateway-linux-amd64 /usr/local/bin/mitrity-mcp-gateway

You should see cosign verify succeed and sha256sum report OK for the binary you downloaded. If either check fails, don't install the binary.

These commands install the Linux amd64 build. For another platform, set --platform to linux/arm64, darwin/amd64 or darwin/arm64, and use the file name that oras pull gives it, for example mitrity-mcp-gateway-darwin-arm64.

On macOS, sha256sum is not installed by default, so use shasum -a 256 --ignore-missing -c checksums.txt instead. Keep --ignore-missing on either platform: checksums.txt covers every platform of the release, and you downloaded only one binary.

Container image

If your agent runs in a container, put the gateway in the same container or pod as the agent, so the agent's MCP client can spawn it:

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

The deployment guide covers container layouts and the sidecar. It also explains why a detached gateway service is not a supported topology.

Step 3: Point your agent at the gateway

Configure your MCP client to launch Mitrity Gateway as its MCP server:

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

From now on, the agent's MCP client starts the gateway with your config file, and the tools the gateway serves go through MITRITY. You don't need proxy environment variables or certificate configuration.

Your agent now has two paths for taking actions, and only one of them is governed:

  • Tools the gateway serves are governed. The gateway evaluates every tools/call before it reaches the upstream. It checks policy, DLP, injection and threat intelligence.
  • Tools built into your agent framework are not. A framework's own shell, code interpreter or file writer never makes an MCP call, so no MITRITY binary sees it. Disable these tools, or treat them as ungoverned:
FrameworkWhat to turn off
Claude Code / Claude Agent SDKpermissions.deny with Bash(...) rules; sandbox.enabled: true with allowUnsandboxedCommands: false; limit allowedMcpServers to the gateway
LangChain / LangGraphOmit ShellTool, PythonREPLTool and FileManagementToolkit from the agent's tool list
OpenAI Agents SDKOmit LocalShellTool. Hosted tools run in OpenAI's cloud and cannot be governed by any local edge
CrewAILeave allow_code_execution at its default False; omit CodeInterpreterTool

Governance Coverage has the full statement of what is and is not governed, the complete table for every framework, and a checklist for making the gateway the only execution path.

Alternative: Mitrity MCP Sidecar. For a simple setup with a single MCP server, you can use Mitrity MCP Sidecar instead. The sidecar wraps one upstream MCP server over stdio. It is the lightest possible deployment option, and of the two it is the only one that runs on Windows.

Step 4: See your first governed event

  1. Trigger an action from your agent.
  2. Open the Audit Log in the dashboard.

Within seconds, you should see events arrive. Each event shows:

  • the agent that performed the action;
  • the action type and its parameters;
  • the policy decision: allow, deny, alert or hold;
  • how long the governance decision took.

Your first agent is now governed. Where to go next: