Guide 25 of 61 · Protecting secrets and data
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.
Built, not yet claimed preview: this guide describes a package that has not passed its release gate.
Give your MCP servers their API keys and OAuth sign-ins from your own terminal: agentgarmd seals each credential, releases it only to the gateway for the one server it belongs to, and the agent never sees a token.
1. Name each server's credentials in policy
The gateway is the only client that holds credentials: the agent talks to each server through the shim and never authenticates, and an Authorization header it sends to a governed server is stripped. The policy names what each server needs. A stdio server takes environment variables, listed in env_secrets; a Streamable HTTP server takes static headers in header_secrets, an OAuth login described by oauth, or both.
Only names go in the policy, never values. A variable the launcher, a loader or an interpreter reads, such as PATH or NODE_OPTIONS, is refused as a secret name.
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"
env_secrets: [FILES_API_TOKEN]
- id: tickets
url: "https://mcp.tickets.example.test/mcp"
header_secrets: [X-Api-Key]
- id: docs
url: "https://mcp.docs.example.test/mcp"
oauth:
issuer: "https://auth.docs.example.test"
client_id: "agentgarm-gateway"
scopes: ["docs:read"]See also
Run MCP servers through the gatewayList 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.
2. Seal a server's API key
Run agentgarm mcp secret set with the server id and the name from the policy, in your own terminal, not inside a session started with agentgarm run: agentgarmd refuses it from inside a governed task. On a terminal it prompts and reads one line with echo off; piped input is read whole, with one trailing newline dropped. The value never goes on the command line. Setting it again replaces it.
Add --header for a name in header_secrets: the session sends it only to that server's URL. If a secret is unset when the agent starts the server, the launch is refused with the agentgarm mcp secret set command to run.
agentgarm mcp secret set files FILES_API_TOKENagentgarm mcp secret set tickets X-Api-Key --header3. Log in to an OAuth server
agentgarm mcp login runs the server's OAuth flow as you, again from outside every governed task. It opens your browser at the authorization server (the address is also printed; with --no-browser it is only printed) and waits 5 minutes. It uses PKCE S256 only, binds the request to the server's URL, checks the response's issuer, and receives the answer on a one-time listener on 127.0.0.1.
The refresh and access tokens go straight to agentgarmd; the CLI keeps nothing. If the authorization server refuses offline_access, the login runs once more without it and says so: refreshing then works only while your session at the authorization server lasts. A stdio server is refused: use mcp secret set.
Unless the policy pins the authorization server with oauth.issuer, everything the login reaches off the MCP server's own origin (the authorization server, its metadata and its endpoints) must be at a public address: one on a loopback, private or link-local address is refused, at login and at every later refresh. For an authorization server inside your network, pin its issuer, as the example does.
agentgarm mcp login docsagentgarm mcp login docs --no-browser4. Sign in once through your company's IdP
When the policy names an enterprise IdP for a server (oauth.idp), log in with --idp: you sign in at the IdP, and that one sign-in serves every server naming the same IdP and client id. The gateway then exchanges it for each server's access token as needed (ID-JAG), with no login at the server; none of the chain reaches the agent. Plain agentgarm mcp login is refused for such a server, and --idp for one without oauth.idp.
The gateway keeps no refresh token from the server, so disabling you at the IdP ends access within one access token, at most 15 minutes.
- id: wiki
url: "https://wiki.example.test/mcp"
oauth:
issuer: "https://auth.wiki.example.test"
client_id: "agentgarm-gateway"
idp: { issuer: "https://idp.example.test", client_id: "agentgarm", scopes: [profile] }agentgarm mcp login wiki --idp5. Know where the credential is kept
Each credential is a sealed secret in agentgarmd's state directory, encrypted under its sealing key and bound to your user and to its server: an OAuth token to the issuer and the server's URL, an API key to the server id and name. An IdP sign-in is bound to the IdP and its client id instead, not to a server. The sealing key is in the keychain on macOS; on a root Linux install it is sealed to the host's TPM 2.0 where there is one, else kept in a root-owned 0600 file reported as software. agentgarm status shows it on the seal-key line under key custody.
agentgarmd releases a value only to agentgarm-session, for a launch of that server in a live task, and records every seal and release in the audit log without the value. An access token lives in the session's memory for at most 15 minutes. On a no-root Linux install the sealing key is a file you own, so any unsandboxed process of yours can read the store.
agentgarm statusSee also
Export and verify the audit logExport AgentGarm's hash-chained audit log, check it against the node key that signs its heads, and know what a passing or broken check tells you.
6. Log in again when asked
When the authorization server rejects the refresh token, or a refresh is interrupted, agentgarmd deletes the credential and raises an mcp-auth alert, and the next launch of that server is refused with the agentgarm mcp login command to run. The gateway never retries a refresh token it has already used. A refresh refused because the token endpoint is not at a public address keeps the credential and raises an mcp-auth alert instead; pin oauth.issuer rather than log in again. Run the login again from your own terminal; the agent's next start of the server gets the new credential.
agentgarm mcp login docs