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 #
- Console → your name (top right) → AI access keys → New Key. Give it a name you will recognise when revoking it.
- Choose the tier. Least privilege that does the job — a key for a reporting assistant should be Read only.
- Copy the key. It is shown once, at creation, and never again. Revoke and reissue if it is lost.
| Tier | Allows |
|---|---|
| Read only | Dashboard, 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 + control | Read, plus start and cancel runs. |
| Read + control + edit | Plus 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 access | Plus delete jobs, create storage targets, create enrolment tokens, add a customer, and read the audit log (platform administrators only). |
| Governance tags | Not 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.
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).
| Tool | Tier | What it does |
|---|---|---|
get_dashboard | Read | The console's front page as numbers: agents online, jobs, last 24 h outcomes. |
list_jobs, get_job | Read | Jobs, with search and paging; one job in full. |
get_job_runs | Read | Run history for a job: status, timings, bytes, the run log, failed files. |
list_agents, get_agent | Read | Machines with online state, version, customer, last check-in. |
get_agent_logs | Read | The agent's own application log as shipped to the console; filter by level or text. |
list_storage_targets | Read | Destinations with provider and last test result. |
browse_storage_target | Read | Folder listing of a target — names, sizes, dates. Never file contents. |
get_storage_usage | Read | How 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_usage | Edit | Measure one destination now rather than using last night’s figure. Slow, and chargeable on a metered provider. |
list_cloud_drives | Read | Drives mounted on an agent. |
list_drive_users, list_user_drives | Read | Drive users (the people who sign in to their own drives on their computers and phones), and the drives each one has. |
browse_backup | Read | What a backup holds, a level at a time: kind, then whose mailbox or drive, then folders. Answers “whose OneDrive is this”. |
search_backup_items | Read | Find items by subject, sender, recipient or filename, narrowed by owner, folder, date or attachments. |
name_backup_owners | Edit | Fills 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_email | Read | One stored email, decoded: subject, sender, recipients, body text and its attachment list. |
list_metadata_schemas | Read | What metadata columns apply to which folders on a destination, their type, and which are required. |
set_metadata_schema | Edit | Define 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_backups | Read | Every 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_summary | Read | What an organisation’s backup holds — counts by record type, and attachments — as at now or as at any past date. |
get_xero_backup_usage | Read | Xero API calls and bytes downloaded this calendar month against the allowance, per organisation or for every billed account the key can see. |
verify_xero_backup | Read | Check 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_invoice | Full access | Platform 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_metadata | Read | One file’s tags, its classification state, and any required columns still missing. |
query_file_metadata | Read | Find tagged files on a destination — by folder, by column value, or everything still needing classification. |
set_file_metadata | Edit | Tag a file. Replaces its whole set of values; unknown column keys are refused. |
list_archive_rules | Read | The 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_rules | Edit | Mark 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_rule | Edit | Remove one folder’s rule; it then follows whatever is marked above it, or nothing. |
list_vss_instances | Read | What a Windows agent can back up application-consistently: Hyper-V VMs, SQL databases, AD. Live from the machine. |
list_machine_disks | Read | A Windows agent's disks: number, size, type, drive letters and whether each can be imaged. Live from the machine. |
list_customers | Read | The customers the key's owner can see. |
list_enrollment_tokens | Read | Active deployment tokens. |
get_customer_health | Read | One 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_report | Read | One 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_usage | Read | Month 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_agent | Read | List a folder on a machine, live. Names, sizes and dates only. |
list_file_versions | Read | Earlier versions of one file at a destination, newest first. |
restore_files | Edit | Restore from a backup onto the machine that made it. Always into a new time-stamped folder — it can never write over live data. |
create_customer | Full access | Add 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_events | Full access | Who did what, and when. Platform administrators only. |
get_access_audit | Full access | Who 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_user | Full access | Add 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_status | Full access | Disable a drive user (a leaver, a lost phone) or enable them again. Every device is signed out at its next request. |
get_stale_data_report | Read | One 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_insights | Read | What 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_jobs | Read | Cloud Agent workers and what they are running. |
run_job, cancel_job | Control | Start a run now; cancel the running one. |
create_job, update_job | Edit | Every option the wizard has: files, storage-to-storage, connector, app-consistent, cloud or agent, schedule, retention. |
update_agent_settings | Edit | Friendly name, concurrent-job limit, upload cap. |
set_hyperv_rct_mode | Edit | Off / Diag / Compose for Hyper-V changed-block incrementals on one agent. |
mount_cloud_drive, unmount_cloud_drive | Edit | Add or remove a drive on an agent. |
assign_user_drive, remove_user_drive | Edit | Give 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_archive | Edit | A one-off archive of a person's mailbox and drive — the leaver workflow. |
preview_office365_pst_export | Read | Before 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_export | Edit | Export 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_exports | Read | The 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_token | Edit | Kill a token early. |
create_enrollment_token | Full access | A deployment token for a customer, with the ready-to-run install command. |
create_storage_target | Full access | A new destination with its credentials. Pass customerTenantId to add it for a customer rather than for yourself. |
clone_storage_target | Full access | A 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_job | Full access | Remove a job and its history. |
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 path | Tool |
|---|---|
GET /mcp/dashboard | get_dashboard |
GET /mcp/insights | get_insights |
GET /mcp/customers/{id}/stale-data | get_stale_data_report |
GET /mcp/customers/health, GET /mcp/billing/usage | get_customer_health, get_billing_usage |
GET /mcp/customers/{id}/monthly-report | get_customer_report |
POST /mcp/agents/{id}/files | browse_agent |
GET /mcp/storage-targets/{id}/versions | list_file_versions |
POST /mcp/restore | restore_files |
POST /mcp/customers, GET /mcp/audit, GET /mcp/audit/access | create_customer, get_audit_events, get_access_audit |
GET /mcp/jobs, GET /mcp/jobs/{id}, GET /mcp/jobs/{id}/runs | list_jobs, get_job, get_job_runs |
POST /mcp/jobs, POST /mcp/jobs/{id}/update, POST /mcp/jobs/{id}/delete | create_job, update_job, delete_job |
POST /mcp/jobs/{id}/run, POST /mcp/jobs/{id}/cancel | run_job, cancel_job |
GET /mcp/agents, GET /mcp/agents/{id}, GET /mcp/agents/{id}/logs | list_agents, get_agent, get_agent_logs |
POST /mcp/agents/{id}/settings | update_agent_settings |
GET /mcp/agents/{id}/mounts, POST /mcp/agents/{id}/mounts, POST /mcp/agents/{id}/mounts/{mountId}/delete | list_cloud_drives, mount_cloud_drive, unmount_cloud_drive |
GET /mcp/agents/{id}/vss-instances | list_vss_instances |
GET /mcp/agents/{id}/machine-disks | list_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}/delete | list_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}/clone | list_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}/delete | list_archive_rules, set_archive_rules, remove_archive_rule |
GET /mcp/customers | list_customers |
GET /mcp/enrollment-tokens, POST /mcp/enrollment-tokens, POST /mcp/enrollment-tokens/{id}/revoke | list_enrollment_tokens, create_enrollment_token, revoke_enrollment_token |
POST /mcp/office365/archives, POST /mcp/google-workspace/archives | create_office365_archive, create_google_workspace_archive |
GET /mcp/office365/pst-exports/preview, POST /mcp/office365/pst-exports, GET /mcp/office365/pst-exports | preview_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 #
- Claude — Claude Code, Desktop and claude.ai step by step
- VS Code — Copilot agent mode with the key in secret storage
- Scripting the API — PowerShell and curl examples for RMM and reports