Demo: Mitrity MCP Sidecar

This self-contained Docker demo shows every governance capability at work in a realistic, scripted scenario. A Claude Agent SDK agent, connected to MITRITY with the mitrity adapter, works through the scenario. Mitrity MCP Sidecar governs both of the agent's entrances, that is, both ways the agent can act:

• MCP tools (read_file, run_command, call_api, …): the SDK starts the sidecar as its MCP server, and the model reaches these tools through it. The sidecar wraps an existing MCP tool server (demo-tools) and passes its catalog through unchanged. It evaluates every tools/call against your policies before the upstream tool sees it.
• The SDK's own built-in tools (Bash, Write, Edit): these never produce an MCP call. Instead, the adapter installs a PreToolUse hook. Before the SDK runs a built-in tool, the hook admits it through the sidecar's loopback admission API. The tool gets the same rules, command analysis, DLP and audit trail as an MCP tool, and its events are stamped surface=agent_hook. If the sidecar cannot be reached, the call is denied.

The demo takes about 14 minutes. You only need Docker Desktop and API keys.

Looking for the gateway version? Demo: Mitrity Gateway is the multi-upstream variant, with tool aggregation and the governed shell.

Want to see multi-agent delegation chains? Demo: Multi-Agent Governance runs a three-container compose stack with real agent-to-agent delegation, per-agent threat intel and privilege boundaries.

Prerequisites

• Docker Desktop (or any Docker runtime)
• A MITRITY account with an active tenant
• An Anthropic API key for the Claude agent

Step 1: Configure your dashboard

Before you run the demo, set up the following in the MITRITY dashboard.

Register an agent

1. Go to Agents > Register Agent and create an agent with these values:
   • Name: demo-agent
   • Mission scope: "Workspace file management and system operations"
2. Under Intent Policy, select Create Policy, enter a name such as demo-policy and select Create. The new policy has allow-all, fail-open defaults, with Prompt Injection Detection and Data Leakage Protection on Enforce. The next section adds the demo's rules to it.
3. Select Register Agent.
4. Copy the Agent Key (ak_...) that the dialog shows. Save the Agent Key: it cannot be retrieved later. Then copy the Agent ID (a UUID) from the agent's detail page.

Add the policy rules

Each tool pattern starts with its surface, which says how the tool is reached:

• An MCP tool passed through by the sidecar is mcp:<tool>, with the upstream's own tool name (mcp:read_file). The sidecar adds no namespace.
• One of the SDK's built-in tools is builtin:<tool> (builtin:bash).

Add the following rules to the agent's policy, to see the full range of governance decisions. Open the policy in /app/policies and select Add Rule for each row: Type is the rule's action, Pattern its tool pattern, and Scope the constraint the rule checks.

These two features of the same policy must be on (Enforce):

• Prompt Injection Detection;
• Data Leakage Protection, with PII and credential patterns (see DLP Pattern Authoring). DLP also applies to builtin:write content, with no extra rule.

Note: A pattern without a surface prefix (read_file on its own) matches nothing. It is an inert rule that looks like protection, and the control plane rejects it when you create or update a policy. The full grammar is in Writing policies.

Created policies for an earlier version of this demo? The policy table used to list bare tool names (read_file, run_command, …). Recreate the rules above with mcp:<tool> patterns, and add the builtin:bash rule for phase 8.

Step 2: Clone and configure

Clone the demo repository and create your .env file:

git clone git@github.com:mitrity-io/iag-demo-mcp-sidecar.git
cd iag-demo-mcp-sidecar
cp .env.example .env

Then edit .env with your values:

ANTHROPIC_API_KEY=sk-ant-...              # Anthropic API key for Claude
MITRITY_AGENT_KEY=ak_...                  # Agent key from dashboard
MITRITY_CONTROL_PLANE_URL=https://api.mitrity.com
MITRITY_AGENT_ID=<uuid>                   # Agent UUID from dashboard

Step 3: Run the demo

docker compose up --build

The container builds locally. The build pulls the Mitrity MCP Sidecar binary from ghcr.io and installs the adapter from PyPI, pinned to mitrity[claude-agent-sdk]==0.2.0. Then the scenario runs, and you can watch its output in your terminal.

To try another adapter release, pass the pin as a build argument: docker compose build --build-arg MITRITY_PYTHON_SPEC='mitrity[claude-agent-sdk]==X.Y.Z'.

What the demo does

The scenario runs seven phases, numbered 1–6 and 8. There is no phase 7 here. Delegation chains and threat intelligence have their own multi-agent demo, which kept the number. There is no phase 9 either: see Why there is no governed-shell phase below.

• Phase 1, Normal Operations: the agent reads workspace files, writes summaries, lists directories, runs safe shell commands and calls APIs. All actions pass through the sidecar, and your policies allow them.

• Phase 2, Policy Violations: the agent tries to read /etc/passwd, run rm -rf, execute curl and issue a DROP TABLE query. The sidecar blocks each action and returns the policy reason.

• Phase 3, Prompt Injection: the agent processes "user input" that contains embedded injection payloads. The sidecar's injection detection engine catches and blocks the attacks before any tool executes.

• Phase 4, DLP & Data Protection: the agent tries to write files that contain API keys and AWS secrets, send notifications with PII (SSNs, credit card numbers) and include credentials in API calls. The sidecar's DLP engine blocks the data exfiltration.

• Phase 5, Escalation & Hold: the agent attempts a production deployment. The sidecar's hold policy pauses the action and creates an approval request, which you can see in your MITRITY dashboard.

• Phase 6, Credential Broker + Hot Rotation: this phase needs a demo_db_password credential definition and a grant for it in your tenant. Create both before you run the demo (see the Credentials docs). In this phase:

  1. The agent calls connect_database with ${credential:demo_db_password} in the connection string.
  2. The sidecar resolves the placeholder through the broker, and the upstream tool returns the password hash.
  3. Mid-phase, you rotate the credential in the dashboard. The next call picks up the new value within 30 seconds, with no agent or sidecar restart.
  4. A final sub-step exercises the fail-closed path with an unknown credential id.

• Phase 8, Built-in Tools (admission hook): the agent uses the SDK's own Bash and Write tools instead of the MCP tools.

  • An allowed ls runs.
  • rm -rf is denied with the policy reason.
  • The same command hidden behind bash -c '…' is still denied, because the edge parses the command tree rather than matching the first word.
  • A .env file full of AWS and Stripe keys, written with Write, is blocked by DLP before it exists.

  Every decision is an audit row with surface=agent_hook.

Why there is no governed-shell phase

The gateway demo has a phase 9 in which the SDK does not execute an admitted built-in Bash at all. Instead, the gateway routes it into its own sandboxed shell (builtin_exec_routing: governed_shell) and runs the judged bytes with egress confined to the agent's destination allowlist. The governed shell is part of the gateway. The gateway demo's image does not serve it as shipped: see its phase 9 requirements.

The sidecar admits built-in Bash through the hook. Every call is judged and audited, and denied when the policy says so. The SDK then runs the allowed command itself.

Keep the demo agent's policy on the default routing (builtin_exec_routing: framework). A policy that routes Bash into an edge without a governed shell gets a deny (routing_unavailable), so the command is not run ungoverned. If you want the governed shell, run the gateway demo.

What to look for

While the demo runs, open your MITRITY dashboard and look at:

• Audit Log: every tool call with its governance decision, latency and policy match. Phase 8 rows carry surface=agent_hook.
• Agent Detail: the demo agent's activity timeline, drift score and Execution coverage card. The card shows what the runtime attested at startup: which built-in tools are hooked, which are not, and which other MCP servers are configured. The admission decisions the sidecar actually saw corroborate it.
• Approval Requests: the held production deployment from Phase 5, waiting for your approval.

When the session starts, the terminal prints the attestation. At the end, it prints a summary with the counts of allowed, blocked and held actions. The summary also has the admission hook's own tally of built-in calls:

• admitted;
• allowed;
• denied;
• held;
• blocked because the edge could not be reached.

Architecture

The entire demo runs inside a single Docker container:

Docker Container
└── Python scenario runner (Claude Agent SDK)
    ├── built-in tools: Bash, Write, Edit ── PreToolUse hook (mitrity adapter)
    │                                          └── admission API (unix:/run/mitrity/admission.sock)
    └── MCP server "mitrity" = Mitrity MCP Sidecar (stdio, governance wrapper)
        └── demo-tools (the wrapped MCP server; catalog passed through unchanged)
            ├── read_file, write_file, list_directory, delete_file
            ├── run_command
            ├── call_api, query_database, send_notification
            └── connect_database (Phase 6 — broker-substituted credential)

One sidecar process serves both entrances: the MCP tools/call stream from the SDK, and the loopback admission API that the hook calls. The sidecar connects to your MITRITY control plane over HTTPS for policy evaluation, event reporting and heartbeat. It also attests the runtime's posture, so the agent's coverage badge reflects what is actually governed. The attestation covers which built-in tools are hooked, which are not, other MCP servers and the permission mode.

Filesystem and shell tools execute for real against the container's /workspace directory. API tools return mock responses.

The adapter is mitrity.claude_agent_sdk.Governor from the mitrity package on PyPI (pip install 'mitrity[claude-agent-sdk]'). scenario/runner.py shows the few lines that wire it up:

• the sidecar is declared as the SDK's MCP server;
• the hook is installed on the built-in tools;
• the SDK's permission callback allows everything MITRITY allows.

To govern your own Claude Agent SDK or Claude Code agent the same way, see Installing the hook.

Gateway vs Sidecar

Both demos run the same governance scenario. The difference is the deployment model, not how faithfully they govern. Both binaries share the same interceptor (TI, delegation, DLP, injection, holds, credential broker), and both serve the loopback admission API. The choice is about where each one sits in the MCP request path:

For a deeper comparison, see Integration modes.

Environment variables

Troubleshooting

• Every built-in tool call is denied with "MITRITY could not authorize this action": the hook could not reach the sidecar's admission API. The sidecar logs its startup on stderr. It refuses to start when /run/mitrity is not owned by the container user, or is group- or world-writable. The image creates the directory as demo, with mode 0700.
• Phase 8's rm -rf runs: the builtin:bash deny rule is missing from the agent's policy.
• An MCP tool call is not decided by the rule you expect: check that the pattern carries its surface prefix: mcp:read_file, not read_file. The decision reason in the demo output and the audit event both name the rule that matched.

Customization

• Policies: change policies in the MITRITY dashboard and re-run the demo to see different behavior.
• Workspace: mount your own files through volumes in docker-compose.yml. The container runs as the unprivileged user demo (uid 1000). On a Linux host, make the mounted directory writable by that uid, or set user: in docker-compose.yml to match its owner.
• Scenarios: edit the files in scenario/phases/ to add your own test prompts.

Next steps

• Demo: Mitrity Gateway: run the same scenario with multi-upstream tool aggregation and the governed shell.
• Demo: Multi-Agent Governance: a three-container stack with real delegation chains, per-agent threat intel and privilege boundaries.
• Governance coverage: what the hook covers in each framework, and how the coverage badge is computed.
• Integration modes: when to use Gateway and when to use Sidecar.
• Writing policies: create your own governance rules.
• Configuration reference: the full sidecar YAML reference.