Skip to the content

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: fetch
agentgarm policy lint ~/.config/agentgarm/agents.d/claude-code.yaml

See also

Allow only vetted MCP servers

Mirror 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 files
sudo agentgarmd mcp-config install codex
sudo 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 -- claude

4. 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 reach

Decide 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 ID

Enrol 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 audit

7. 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 --open
agentgarm status
The dashboard's MCP screen: the task filter and rating, then a tab per kind of record, each gated call with its decision

See also

Check that protection is on

See 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 -- claude

See also

Sign in to MCP servers without exposing tokens

Give 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.