Guide 24 of 61 · Protecting secrets and data
Run MCP servers through the gateway
List the MCP servers an agent may use, pinned to a package and hash, and run each through the gateway, where agentgarmd decides every tool call first.
Built, not yet claimed preview: this guide describes a package that has not passed its release gate.
List the MCP servers your agent may use in its policy, pinned to an exact package and hash; point the agent's MCP configuration at the gateway; and each stdio server then runs in a sandbox of its own, inside the agent's task, with each tool call decided by agentgarmd before the server sees it.
1. Declare the server in policy
Add an mcp section under security_boundaries in your agent's policy, such as claude-code.yaml. Each server is an id and either a package named in packages or the url of a Streamable HTTP server; there is no way to give the gateway a command. A package entry needs an exact version and its integrity: the registry's sha512- hash for npm, or sha256: and the wheel's or sdist's hash for PyPI.
Lint the file: it reports a server whose package packages does not list. Then restart agentgarmd, which reads the policy directory when it starts, as in the first guide.
security_boundaries:
mcp:
packages:
- ecosystem: npm
name: "@example/files-mcp"
version: "2.3.1"
integrity: "sha512-dKwwYx2jsNYzsQo3cvsJLbY0T9qnN4E2tlW/xSHIlrSecFHpe0HKJMm8oUVmjlVUrWWhECN+8b1v1zv+WxMJ1Q=="
servers:
- id: files
package: "@example/files-mcp@2.3.1"
sandbox:
write_roots: ["${WORKSPACE}/out"]
egress_hosts: ["api.example.test"]
package_hosts: fetchagentgarm policy lint ~/.config/agentgarm/agents.d/claude-code.yamlSee also
Allow only vetted MCP serversMirror the MCP registry, have Central Lite sign it for your machines, and let agents launch only servers resolved from that signed snapshot.
2. Point the agent at the gateway
The agent's MCP configuration must start each server as agentgarm mcp run <id>, the shim, which passes only the server id and relays the agent's messages. On a root install, sudo agentgarmd mcp-config install claude-code writes that entry for every server in the policy into Claude Code's machine-wide managed-mcp.json, so Claude Code loads only those servers from its own configuration (claude.ai connectors, Claude in Chrome and in-process SDK servers can still load). For codex it writes an allow-list into Codex's requirements.toml, which defines no server: Codex also needs each server in the user's own configuration, so run the install again with --for-user and that user's name. On a no-root install add --user, which rewrites your own ~/.claude.json, ~/.codex/config.toml or ~/.cursor/mcp.json; Cursor has only that form. Other agents have no such install: list the shim in their configuration yourself. When CODEX_HOME is set to an absolute path, the Codex install with --user writes $CODEX_HOME/config.toml instead, as Codex reads it; run status and remove with the same CODEX_HOME. With --for-user, root cannot see that user's CODEX_HOME, so pass it as --codex-home <dir> (a directory inside that user's home); without it the install writes ~/.codex/config.toml and says so.
agentgarmd watches these files, restores them when they are changed and rewrites them when the policy changes. A server configured any other way in Claude Code's, Codex's or Cursor's configuration files is reported as MCP_UNGOVERNED and lowers the task's assurance. A server started from the command line or the shell is not detected yet.
agentgarm mcp run filessudo agentgarmd mcp-config install codexsudo agentgarmd mcp-config install codex --for-user <user>3. Start the agent inside a task
The shim works only inside a governed task, so start the agent with agentgarm run. When the agent starts a server, the shim asks agentgarmd for a single-use ticket bound to the task and server, and agentgarm-session redeems it and launches the server from the policy's entry. If it cannot (outside a task, a server not in the policy, no agentgarmd or no session), the agent gets a JSON-RPC error starting AgentGarm MCP gateway: and the shim exits 1.
For an agent whose MCP client speaks only HTTP, agentgarm run --mcp-listen <id> opens a loopback listener for the task instead and writes its URL and token to a 0600 file named by $AGENTGARM_MCP_CONFIG; it is rated C, and it is refused for Claude Code while its managed-mcp.json exists.
agentgarm run -- claude4. Know what each server's sandbox allows
Before the server runs, the gateway fetches the package and checks it against the policy's hash; a range, a missing entry or a different hash and the server never starts. The server then runs in a sandbox of its own, in a private directory the agent cannot read: it can write the task's write roots and its sandbox.write_roots, its environment is a fixed allow-list, and its network goes through the proxy. It dies with its shim, its task or the session; on Linux with delegated cgroups it sits in the task's cgroup, under the task's limits.
egress_hosts gives a stdio server a proxy listener of its own that reaches only those hosts and its package registry. On macOS the sandbox holds the server to that listener; on Linux it limits the port only, so a hostile server can reach other hosts on that port, and below Landlock ABI 4 it does not limit TCP at all. package_hosts: fetch closes the npm registry once the package is fetched.
See also
Limit what an agent can read, write and reachDecide which files an agent may read and write and which hosts it may reach, know which layer holds each rule, and recognise a denial.
5. Decide each tool call
Every tools/call, resources/read and prompts/get is decided by agentgarmd, and only an allow reaches the server. A deny, an ask, or no answer within 250 ms is answered to the agent as an error, unless the server is marked on_decide_timeout: fail_open_alert, which forwards a call left undecided, or one agentgarmd cannot be reached for, with an alert and lowers the task's assurance; a policy in the strict or ephemeral profile does not compile with that setting. Tools take classes from tool_classes or AgentGarm's signed taxonomy; an unclassed tool counts as destructive and open_world, and a server's own hints can only add classes.
flow_rules look at what the task tree did earlier, hook decisions included: with the rule below, a secret read followed by a curl or the server's upload tool is denied. On a root install with a presence key, an ask prompts for your approval and the agent's retry of the same call is allowed once; otherwise it is refused. In audit mode calls are allowed and the verdict recorded.
The gateway also scans every message it relays, both ways, with the same secret rules as the proxy, under the policy's security_boundaries.dlp.on_secret. With alert, the default and what audit mode always does, a finding is recorded and the message goes through unchanged. In enforce mode, redact replaces each secret in the message's JSON strings with the same placeholder the proxy uses, before anything decides the message, and deny refuses the message. A message that cannot be redacted, or is over 4 MiB, is refused under either.
tool_classes:
read_credentials: [secrets_read]
upload: [network_egress]
flow_rules:
- id: no-exfil
deny: { after: secrets_read, tools: [network_egress] }
- id: ask-before-posting
ask: { after: fs_read, tools: [messaging_send] }See also
Approve risky actions with Touch IDEnrol a Touch ID key on your Mac and approve each command your policy asks about with your fingerprint, for that one call only.
6. Check the servers against advisories
agentgarm mcp audit reads the advisory pack agentgarmd verified and prints, for every server in your policies, what the gateway would do at launch: DENY for a known-malicious version or a policy set to deny, ALERT, OK, or NOT CHECKED for an HTTP server or a package missing from mcp.packages. It starts with the pack's state and exits 1 when a configured server would be refused. Add --json for scripts.
agentgarm mcp audit7. See what the gateway did
The dashboard's MCP screen shows, per task, the servers launched and whether their package verified, the tools held back or quarantined, changed tool definitions, and advisory findings. The gateway is built but its configuration custody is not yet proven by a live run, so agentgarm status rates MCP C on every platform and install, and a policy that configures MCP keeps a launched session from rating B.
agentgarm ui --openagentgarm statusSee also
Check that protection is onSee whether AgentGarm's services are up, what assurance level each agent session has and why, and what to do about a bypass alert.
8. Follow one server from policy to tool call
The files server above runs through all three MCP guides, in order. Here it is declared, pinned and sandboxed, and its tool classes feed the flow rules. In the next guide its API token is sealed by agentgarmd, so the agent never holds it; in the registry guide, on a fleet, its version comes from your signed registry instead of a hand-written pin. On one machine, once the next guide has added env_secrets: [FILES_API_TOKEN] to the server, the whole path is: lint the policy, restart agentgarmd to load it, seal the token, audit the servers you allowed, then start the agent. Do the three guides in this order: each one assumes the server the one before it set up.
agentgarm policy lint ~/.config/agentgarm/agents.d/claude-code.yaml
systemctl --user restart agentgarmd
agentgarm mcp secret set files FILES_API_TOKEN
agentgarm mcp audit
agentgarm run -- claudeSee also
Sign in to MCP servers without exposing tokensGive your MCP servers their API keys and OAuth sign-ins from your own terminal; agentgarmd seals each one and the agent never sees a token.