Docs / AI agents (MCP)

AI agents (MCP)

SafeGrd speaks the Model Context Protocol, so a coding agent can check your backups, take one before a risky migration and prove it restores, without anyone opening the console. There are two servers. The remote one reads every host's state and asks for a backup or a drill. It never holds data or decrypts anything. The local one runs on a host and backs up, verifies and restores with that host's config and key.

The remote server is included on every paid plan; on the free plan it answers 402 with the reason. The local server is part of the CLI and needs no plan.

Server	Where it runs	What it can do
Remote	`https://safegrd.dev/mcp`	Read organizations, projects, surfaces, snapshots and drills; ask for a backup or a Fire Drill now; read storage use and drill statistics.
Local	`safegrd mcp`, on the host	Status, list, doctor, back up, verify, restore into a new or empty target, and export.

What an agent cannot do

No tool deletes a snapshot, changes where backups are stored, rotates a key, or changes billing or members. The server refuses these to a personal access token on every API route, so a token cannot do them through REST either. A snapshot under compliance-mode Object Lock cannot be deleted before its lock expires, by anyone. Every tool is marked non-destructive in its MCP annotations, and the read tools are marked read-only, so a client can run them without asking each time.

Every request_backup and request_drill, and the same requests made from the console, is listed on the console's Tokens page with the person, the token's name, whether it came over MCP, and whether it was accepted.

The remote server

Create a personal access token in the console under Tokens, then add the server to your client. In Claude Code:

claude mcp add --transport http safegrd https://safegrd.dev/mcp \
  --header "Authorization: Bearer sg_pat_..."

Or install the Claude Code plugin, which asks for the token and adds skills that back up and run a Fire Drill before a risky change, and report on backup health. Its source is safegrd/agent-plugins.

/plugin marketplace add safegrd/agent-plugins
/plugin install safegrd@safegrd

Any client that supports the Streamable HTTP transport and a bearer header works the same way. The server is stateless: every call is checked against the token as it stands, so revoking the token in the console stops the agent on its next call.

Tool	Arguments	What it does
list_organizations		Organizations the token belongs to, with plan and quotas.
list_projects	org_id	An organization's projects, such as production and staging.
list_surfaces	project_id, limit, cursor (all optional)	Databases, file trees, mailboxes and hosts, with last backup, drill and alert state.
get_surface	node_id	One surface or host.
list_snapshots	node_id; limit, cursor (optional)	A surface's snapshots, newest first: when, how big, locked until when, and whether a drill verified them.
get_snapshot	snapshot_id	One snapshot's recorded metadata: digests, counts, lock, Threat Shield verdict.
list_drills	node_id; limit, cursor (optional)	A surface's Fire Drill reports, newest first, with their assertions and signatures.
request_backup	node_id	Ask for a backup now. Refused within an hour of the last backup, because each one is locked and stored until it expires.
request_drill	node_id	Ask for a Fire Drill of the latest snapshot now. Counted against the plan's drill cadence.
storage_usage	org_id	Hosted storage: whether it is offered, the quota and how much is locked.
drill_stats	org_id	Fire Drill pass rate and results across an organization.

The remote server runs nothing itself. On a surface your host backs up, a request is picked up by the daemon at its next check-in, so the host needs the daemon running for request_backup and request_drill to do anything. A surface set to Back up on SafeGrd or Drill on SafeGrd in the console is queued on SafeGrd instead, and needs no daemon. A refusal comes back as a tool error in the API's own words, so the agent can tell you why.

The three list tools return {"items": [...], "next_cursor": "..."}, 25 at a time unless limit says otherwise (up to 200). Pass next_cursor back as cursor for the next page; it is absent on the last one.

The local server

safegrd mcp serves this host's SafeGrd over stdio, for an agent running on the same machine. In Claude Code:

claude mcp add safegrd -- safegrd mcp

Each tool runs the CLI command of the same name with this host's config, and refuses what the command refuses. Two more limits:

No tool takes a private key. The host's key_path is used, so your key never passes through an agent's context.
restore writes only into a new or empty directory, or a database the restore confirms is empty. An agent cannot restore over data.

Tool	Arguments	Runs
status		`safegrd status`
list		`safegrd list`
doctor		`safegrd doctor`
backup	surface or files (optional)	`safegrd backup --surface` for one surface of the host's config, `--files` for a directory tree, or the configured database
verify	snapshot_id, sandbox_url (optional)	`safegrd verify --dry-run`, or a full drill into an empty database
restore	snapshot_id, and target_dir or target_url	`safegrd restore` into an empty target
export	to_dir, or to_bucket and to_endpoint	`safegrd export`, still encrypted

The REST API underneath

Every remote tool is a call to the same /api/v1 routes the console uses. The routes an agent needs are described in /openapi.json, and /llms.txt points an agent at these docs. The remote server's tools are listed without a token at /.well-known/mcp/server-card.json.