MCP tools

The Norcube MCP server exposes seven Backup tools, so an AI agent (Claude, Claude Code, Cursor, ChatGPT…) can take a fresh backup before it does something risky and prove that a backup actually restores. Connecting, consent and scopes are covered on the platform page; this page documents the Backup tools themselves.

backup.write and backup.verify are off by default on the consent screen, and independent of each other. A connection without them can look, but never start a backup or a restore check. The Backup API enforces this too, not only the MCP tools. To allow them later, edit the connection in Account → Connected apps (see Changing a connection's access).

None of the tools reads your data, runs queries, downloads a backup or restores into your own database.

If the connection covers more than one organization, every tool also takes an organization argument (the organization id); with a single-org connection it's implicit. See Organizations.

backup_list_datasources

Lists the datasources in the organization: id, name, engine, environment, whether credentials are stored, the last backup time and size, and the next scheduled run. Results are paged with cursor / nextCursor; there's no search filter, so agents page through and match by name. Agents use it to turn "the production database" into the datasource id the other tools need, instead of guessing.

backup_list_jobs

Lists one datasource's backup jobs, newest first: status, trigger (manual or schedule), times, size and error summary, plus the latest restore test of each backup (restoreCheck: status, passed, warnings, and its id). Paged with limit (default 10, max 50) and cursor. Agents use it for "when was the last successful backup of prod?" and to pick a backup for backup_run_restore_check.

backup_run

Starts an on-demand backup of one datasource. It's the same operation as Run backup now in the dashboard (a manual-trigger backup job), so everything about manual runs applies:

• Input: the datasource id, and optionally a policy id. Without a policy, the datasource's highest-priority enabled policy attachment is used; with one, that policy must be attached to the datasource.
• Output: the new job's id. The call returns as soon as the job is queued; it does not wait for the dump.
• Preconditions: the datasource needs stored credentials and at least one enabled policy attachment. If not, the tool returns an error saying which is missing.
• Not idempotent: each call queues a new job. Parallel runs of the same datasource are allowed by design, so an agent that retries blindly gets two backups, not an error.
• Audited and billed like any manual run: it writes the backup_job.manual_run audit entry and counts against your plan.

backup_get_status

Returns a job's current state, given the job id from backup_run. The statuses are the usual job lifecycle:

The response also carries a terminal flag. The status type reserves two more values, partial and canceled; neither is produced today, but agents should key off terminal rather than a hard-coded list.

Polling semantics. Keep polling while terminal is false (that is, while the job is queued or running). Poll at a modest interval (every 10–30 seconds is plenty) rather than in a tight loop; you share the MCP server's per-user rate limit with every other tool call. There's no upper bound on duration: the job runs as long as the dump takes, and stuck jobs are resolved automatically.

Restore checks

A restore check is the restore test you can start with Test now in the dashboard: the backup is restored into a throwaway database (the Norcube-managed engine, or a fresh database on your scratch server) and validated, then thrown away. It never touches the database you back up.

backup_restore_check_overview

The datasource's restore-test setup and track record: whether automated tests run (mode: off, every Nth backup, cron schedule or random sample), the target, the validation depth, when the last test ran, the last 10 finished tests (newest first) with how many passed, and a one-line summary the agent can relay, such as "the most recent restore check FAILED".

backup_run_restore_check

Starts a test restore of one backup and returns a restoreCheckId immediately.

• Input: the datasource id and, optionally, a backup job id. Without one, the most recent successful backup (among the last 50 jobs) is tested.
• Target: the datasource's configured test target, or the managed engine when nothing is configured, exactly like Test now.
• Errors: a backup that can't be restored (not successful, or its archive is gone), a backup too large for the managed engine, or an engine the managed target doesn't support come back as readable errors; the last two mean "configure a scratch target".
• Permission: needs backup.verify (Run restore checks on the consent screen). backup.write alone doesn't allow it, and the Backup API enforces that too.

backup_get_restore_check

Polls a test started by backup_run_restore_check (or one listed by backup_list_jobs). It returns the status, a terminal flag, whether the restored database passed validation, the depth reached (l1 restore only, l2 sanity checks, l3 your validation query), warnings ("passed with warnings") and the error summary. Poll every 30 to 60 seconds; a test takes a few minutes, longer for large databases.

Workflow: back up before a deploy

The intended use is a guard step before anything destructive.

Before you run a migration, ask your agent to back up the production database; it calls backup_run and waits for backup_get_status to report success.

What the agent does under the hood:

To make this automatic in Claude Code, put the rule in the repository's CLAUDE.md, for example: "Before running any database migration, back up the prod datasource with the norcube MCP tools and wait for success."

Backups don't lock your database (pg_dump only takes ACCESS SHARE locks), but on PostgreSQL schema changes wait for the dump to finish, which is one more reason to let the backup complete before migrating.

Workflow: is my backup actually restorable?

Has our production backup ever been restore-tested?

The agent calls backup_restore_check_overview. If no test has passed recently and the connection has backup.verify, it can offer to run one: backup_run_restore_check, then backup_get_restore_check until terminal, and report whether the backup restored cleanly.

What's not here

Restores into your own databases, downloads, deleting backups and policy management aren't exposed through MCP, on purpose: a restore can overwrite a database and a download hands over a full copy of it. Use the dashboard or the CLI for those.

Related

• MCP server: connecting clients, scopes, organizations, errors.
• Backup jobs: statuses, downloads, stuck-job recovery.
• Restore testing: targets, validation depth, automated cadence.
• Backup CLI: the terminal equivalent, including org-wide job listings.