CaryvaneHelp
/
EN

AI assistants & API

Caryvane exposes an MCP server and a matching REST API, authenticated by personal access keys. An assistant with a key can answer "which backups failed last night?", run a job, enrol a machine, or set up a customer's storage — bounded by the key's tier and by what the user who issued it is allowed to see.

Create a key #

  1. Console → your name (top right) → AI access keys → New Key. Give it a name you will recognise when revoking it.
  2. Choose the tier. Least privilege that does the job — a key for a reporting assistant should be Read only.
  3. Copy the key. It is shown once, at creation, and never again. Revoke and reissue if it is lost.
TierAllows
Read onlyDashboard, jobs, run history and logs, agents and their logs, storage targets, customers, enrolment tokens, cloud fleet status, what run history suggests is going wrong, one customer’s whole position, and billable seats month by month. Also browsing — both a destination and a folder on one of your machines — which returns names, sizes and dates and never file contents.
Read + controlRead, plus start and cancel runs.
Read + control + editPlus create and edit jobs, start a restore (always into a new folder, never over live data), change agent settings, mount and unmount cloud drives, revoke enrolment tokens, create Microsoft 365 / Google archives, export a backed-up mailbox to PST, set an agent's Hyper-V incremental mode.
Full accessPlus delete jobs, create storage targets, create enrolment tokens, add a customer, and read the audit log (platform administrators only).
Governance tagsNot an assistant tier. For Caryvane Governance only: list storage targets (credentials never included), browse folders and files by name, read metadata columns and tags, read archiving rules and the archive summary, and set tag values — one file or up to 500 per call, each recorded as a Governance suggestion with its confidence. No jobs, no runs, no restores, no file content, and none of the MCP tools. Routes live under /governance/ with the same bearer header.

A key sees exactly what its owner sees: an MSP admin's key sees that MSP's customers, a customer user's key sees one customer. Every action a key takes is written to the audit log under the owner's name. Keys are revoked from the same dialog and stop working at once.

Treat a key like a password

Anyone holding a Full-access key can enrol machines into your customers and point backups at their own storage. Keep keys in the assistant's own secret store, never in a shared document.

Connect Claude #

The MCP server is a single HTTP endpoint, https://console.caryvane.com/mcp/rpc, with the key as a bearer token. In Claude Code, add to .mcp.json in the project (or ~/.claude.json for every project):

{
  "mcpServers": {
    "caryvane": {
      "type": "http",
      "url": "https://console.caryvane.com/mcp/rpc",
      "headers": { "Authorization": "Bearer <key>" }
    }
  }
}

Or from the terminal: claude mcp add --transport http caryvane https://console.caryvane.com/mcp/rpc --header "Authorization: Bearer <key>". Claude Desktop and claude.ai take the same URL and header under Settings → Connectors → Add custom connector. After connecting, ask it to list the tools; the description of each is written for the assistant, so it knows to check list_agents before create_job.

Connect VS Code (Copilot agent mode) #

Add to .vscode/mcp.json (VS Code prompts for the key once and stores it in its secret storage):

{
  "inputs": [
    { "id": "caryvane-key", "type": "promptString", "password": true, "description": "Caryvane access key" }
  ],
  "servers": {
    "caryvane": {
      "type": "http",
      "url": "https://console.caryvane.com/mcp/rpc",
      "headers": { "Authorization": "Bearer ${input:caryvane-key}" }
    }
  }
}

The tools #

Names are the same in MCP and in the REST API below. Tier is the minimum key tier (Read = Read only, Control = Read + control, Edit = Read + control + edit).

ToolTierWhat it does
get_dashboardReadThe console's front page as numbers: agents online, jobs, last 24 h outcomes.
list_jobs, get_jobReadJobs, with search and paging; one job in full.
get_job_runsReadRun history for a job: status, timings, bytes, the run log, failed files.
list_agents, get_agentReadMachines with online state, version, customer, last check-in.
get_agent_logsReadThe agent's own application log as shipped to the console; filter by level or text.
list_storage_targetsReadDestinations with provider and last test result.
browse_storage_targetReadFolder listing of a target — names, sizes, dates. Never file contents.
get_storage_usageReadHow much is stored at each destination, with the date it was measured. Cached from the nightly sweep; a destination with no figure is reported as such, never as zero.
measure_storage_usageEditMeasure one destination now rather than using last night’s figure. Slow, and chargeable on a metered provider.
list_cloud_drivesReadDrives mounted on an agent.
list_drive_users, list_user_drivesReadDrive users (the people who sign in to their own drives on their computers and phones), and the drives each one has.
browse_backupReadWhat a backup holds, a level at a time: kind, then whose mailbox or drive, then folders. Answers “whose OneDrive is this”.
search_backup_itemsReadFind items by subject, sender, recipient or filename, narrowed by owner, folder, date or attachments.
name_backup_ownersEditFills in which mailbox, drive or site each catalogued item came from, and names those ids. Run once per job after upgrading; only fills gaps.
read_backup_emailReadOne stored email, decoded: subject, sender, recipients, body text and its attachment list.
list_metadata_schemasReadWhat metadata columns apply to which folders on a destination, their type, and which are required.
set_metadata_schemaEditDefine the columns a folder’s files may carry, creating the set or replacing it; an empty folder path means the container’s root, and columns inherit down the tree. Read list_metadata_schemas first: this replaces the folder’s columns.
list_xero_backupsReadEvery Xero organisation the key can see, customer by customer: connected or needing the customer to sign in to Xero again, where it is backed up, whether the first backup has finished, how the last run went. Start here for “is Xero backed up?”
get_xero_backup_summaryReadWhat an organisation’s backup holds — counts by record type, and attachments — as at now or as at any past date.
get_xero_backup_usageReadXero API calls and bytes downloaded this calendar month against the allowance, per organisation or for every billed account the key can see.
verify_xero_backupReadCheck a backup against Xero’s own trial balance: receivables and payables rebuilt from the backed-up invoices, credit notes and overpayments must match it. Makes no Xero calls.
preview_xero_backup_invoiceFull accessPlatform admin: what a customer’s Xero backup invoice for a calendar month would be — organisations, data used and included, overage, total. Saves and sends nothing.
get_file_metadataReadOne file’s tags, its classification state, and any required columns still missing.
query_file_metadataReadFind tagged files on a destination — by folder, by column value, or everything still needing classification.
set_file_metadataEditTag a file. Replaces its whole set of values; unknown column keys are refused.
list_archive_rulesReadThe archiving rules on a destination: which folders are marked, how old a file must be, and whether archiving is switched on for that destination at all.
set_archive_rulesEditMark folders for archiving, many at once with the same rule — the shape a request like “archive 5445 to 5460 after a year” really has. The reply lists the rules as stored and any folder that was refused. Rules do nothing until an archive sweep job runs.
remove_archive_ruleEditRemove one folder’s rule; it then follows whatever is marked above it, or nothing.
list_vss_instancesReadWhat a Windows agent can back up application-consistently: Hyper-V VMs, SQL databases, AD. Live from the machine.
list_machine_disksReadA Windows agent's disks: number, size, type, drive letters and whether each can be imaged. Live from the machine.
list_customersReadThe customers the key's owner can see.
list_enrollment_tokensReadActive deployment tokens.
get_customer_healthReadOne customer’s whole position for a ticket: quiet machines, jobs whose last run failed or warned, jobs never run, destinations that lost their sign-in.
get_customer_reportReadOne customer’s monthly report as figures, never the email: the archived report as sent, or built live. Not measured is not zero. With includePdf it also returns the branded PDF.
get_billing_usageReadMonth by month per customer: machines at month end, cloud credits and GB used, invoiced total and whether it was paid. The month in progress is a running total, not a bill.
browse_agentReadList a folder on a machine, live. Names, sizes and dates only.
list_file_versionsReadEarlier versions of one file at a destination, newest first.
restore_filesEditRestore from a backup onto the machine that made it. Always into a new time-stamped folder — it can never write over live data.
create_customerFull accessAdd an account anywhere in your own tree — a client, or for a distributor an MSP beneath them. Pass parentTenantId and tenantType; the server refuses a combination the parent cannot own.
get_audit_eventsFull accessWho did what, and when. Platform administrators only.
get_access_auditFull accessWho restored, downloaded, previewed, browsed or deleted what, for the customers your key can see, filtered by customer, period, action type and person. See the access report.
add_drive_userFull accessAdd a drive user to a customer, signing in with Microsoft, Google or a password. Where the customer has connected Microsoft 365 or Google Workspace, the person must be an enabled member there (not a guest), and their account is linked so nobody from another organisation can sign in as them.
set_drive_user_statusFull accessDisable a drive user (a leaver, a lost phone) or enable them again. Every device is signed out at its next request.
get_stale_data_reportReadOne customer’s stale and orphaned data: files not modified in N years, mailboxes and drives of people who have left, and what could move to the archive, with draft archiving rules it never applies. See Stale data report.
get_insightsReadWhat run history suggests: jobs going wrong more often than they were, how much each is moving against the month before, and which are still building history.
get_cloud_fleet, get_cloud_worker_jobsReadCloud Agent workers and what they are running.
run_job, cancel_jobControlStart a run now; cancel the running one.
create_job, update_jobEditEvery option the wizard has: files, storage-to-storage, connector, app-consistent, cloud or agent, schedule, retention.
update_agent_settingsEditFriendly name, concurrent-job limit, upload cap.
set_hyperv_rct_modeEditOff / Diag / Compose for Hyper-V changed-block incrementals on one agent.
mount_cloud_drive, unmount_cloud_driveEditAdd or remove a drive on an agent.
assign_user_drive, remove_user_driveEditGive a drive user a cloud drive, or take it away. It follows them to every computer and phone they sign in on. Files in storage are never touched.
create_office365_archive, create_google_workspace_archiveEditA one-off archive of a person's mailbox and drive — the leaver workflow.
preview_office365_pst_exportReadBefore an export: how many messages a selection covers and about how big they are, from the backup’s catalogue alone. A mailbox, optionally one folder (with or without its subfolders), and all mail, only mail older than N days, or a date range. Nothing is read from storage; messages catalogued without a size make the total an under-estimate.
create_office365_pst_exportEditExport mail a Microsoft 365 backup already holds to PST files, split at about 3 GB, with a report beside them naming every message left out. Same selection as the preview; the files go to a folder on one of the customer’s agents or to a storage target, run by the agent that owns the backup, another of the customer’s agents, or the Caryvane cloud (one cloud credit; storage target only). The backup is only read. Not on a trial. See Export to PST.
list_office365_pst_exportsReadThe exports requested so far and how each ended: messages written, skipped and failed, how many PST files, and where they and the report are. Optionally for one backup job.
revoke_enrollment_tokenEditKill a token early.
create_enrollment_tokenFull accessA deployment token for a customer, with the ready-to-run install command.
create_storage_targetFull accessA new destination with its credentials. Pass customerTenantId to add it for a customer rather than for yourself.
clone_storage_targetFull accessA new destination that reuses an existing one's credentials without anyone handling the keys: they stay on the server. Choose a new bucket (optionally created with Object Lock) and version history; immutability is never copied. Not for storage connected by sign-in.
delete_jobFull accessRemove a job and its history.
Resellers

When the key's owner can see several customers, tools that create things take a customer: create_job infers it from the agent, or needs customerTenantId for a Cloud Agent job; create_enrollment_token takes tenantId. Nothing can be created across a customer boundary — a job cannot read one customer's storage and write another's.

The REST API #

The same operations as plain JSON over HTTPS, for scripts, RMM integrations and any assistant that speaks HTTP rather than MCP. Same key, same header: Authorization: Bearer <key>. Responses are JSON; errors are standard status codes with a message.

curl -s https://console.caryvane.com/mcp/jobs?take=50 \
  -H "Authorization: Bearer <key>"

curl -s -X POST https://console.caryvane.com/mcp/jobs/14/run \
  -H "Authorization: Bearer <key>"
Method and pathTool
GET /mcp/dashboardget_dashboard
GET /mcp/insightsget_insights
GET /mcp/customers/{id}/stale-dataget_stale_data_report
GET /mcp/customers/health, GET /mcp/billing/usageget_customer_health, get_billing_usage
GET /mcp/customers/{id}/monthly-reportget_customer_report
POST /mcp/agents/{id}/filesbrowse_agent
GET /mcp/storage-targets/{id}/versionslist_file_versions
POST /mcp/restorerestore_files
POST /mcp/customers, GET /mcp/audit, GET /mcp/audit/accesscreate_customer, get_audit_events, get_access_audit
GET /mcp/jobs, GET /mcp/jobs/{id}, GET /mcp/jobs/{id}/runslist_jobs, get_job, get_job_runs
POST /mcp/jobs, POST /mcp/jobs/{id}/update, POST /mcp/jobs/{id}/deletecreate_job, update_job, delete_job
POST /mcp/jobs/{id}/run, POST /mcp/jobs/{id}/cancelrun_job, cancel_job
GET /mcp/agents, GET /mcp/agents/{id}, GET /mcp/agents/{id}/logslist_agents, get_agent, get_agent_logs
POST /mcp/agents/{id}/settingsupdate_agent_settings
GET /mcp/agents/{id}/mounts, POST /mcp/agents/{id}/mounts, POST /mcp/agents/{id}/mounts/{mountId}/deletelist_cloud_drives, mount_cloud_drive, unmount_cloud_drive
GET /mcp/agents/{id}/vss-instanceslist_vss_instances
GET /mcp/agents/{id}/machine-diskslist_machine_disks
GET /mcp/drive-users, POST /mcp/drive-users, PATCH /mcp/drive-users/{id}list_drive_users, add_drive_user, set_drive_user_status
GET /mcp/drive-users/{id}/drives, POST /mcp/drive-users/{id}/drives, POST /mcp/drive-users/{id}/drives/{driveId}/deletelist_user_drives, assign_user_drive, remove_user_drive
GET /mcp/storage-targets, POST /mcp/storage-targets, GET /mcp/storage-targets/{id}/browse, GET /mcp/storage-targets/usage, POST /mcp/storage-targets/{id}/measure-usage, POST /mcp/storage-targets/{id}/clonelist_storage_targets, create_storage_target, clone_storage_target, browse_storage_target, get_storage_usage, measure_storage_usage
GET /mcp/storage-targets/{id}/archive-rules, POST /mcp/storage-targets/{id}/archive-rules, POST /mcp/storage-targets/{id}/archive-rules/{ruleId}/deletelist_archive_rules, set_archive_rules, remove_archive_rule
GET /mcp/customerslist_customers
GET /mcp/enrollment-tokens, POST /mcp/enrollment-tokens, POST /mcp/enrollment-tokens/{id}/revokelist_enrollment_tokens, create_enrollment_token, revoke_enrollment_token
POST /mcp/office365/archives, POST /mcp/google-workspace/archivescreate_office365_archive, create_google_workspace_archive
GET /mcp/office365/pst-exports/preview, POST /mcp/office365/pst-exports, GET /mcp/office365/pst-exportspreview_office365_pst_export, create_office365_pst_export, list_office365_pst_exports

Parameters are the tool's arguments as JSON in the body (POST) or the query string (GET). The MCP tool descriptions, which the assistant sees, are the authoritative field reference; an OpenAPI document for building a ChatGPT Custom GPT Action is on the list but not published yet.

What an assistant cannot do #

By design there is no tool that downloads a file's contents, deletes files from storage, or moves them. Browsing returns metadata only, whether it is a destination or a folder on one of your machines.

An assistant can start a restore, and two things bound what that means. The files move between your storage and your machine without passing through the assistant or through us: the agent fetches them from your storage directly. And a restore can never write over what is already there — it always lands in a new time-stamped folder inside the folder you name, so the copy you were about to compare against is still where you left it. Moving anything back is a person's decision. Every restore is a job, so it appears in the job list and its run history like any other.

The one operation that removes data — an Archiving job with source removal switched on — is created like any other job, with the gate off unless explicitly set, and every file it removes is recorded in the catalogue first.

read_backup_email is the one place an assistant sees the inside of something, so it is worth being exact about what that means. It reads a message you already asked us to back up, decoded from the copy in your own storage, and only when asked for that specific item by id. It is not a search of message bodies: search_backup_items matches subjects, senders, recipients and filenames, never body text. Nothing indexes what is inside your mail.

Tagging deserves its own note, because it looks harmless and is not quite. set_file_metadata replaces a file’s whole set of values rather than merging into it, so anything you leave out is removed — read the file first if you mean to change one column. And an archiving rule can be conditioned on a tag, so changing one can change whether a file is eventually archived. It still cannot cause a file to be archived that was not already old enough and already covered by a rule: a condition only ever narrows.

Metadata is never read from inside your files. It is what somebody typed, or what came across from SharePoint, Egnyte or Google Drive — we do not open a document to decide what it is about.

Go deeper #