MCP Server | XMigrate Docs

Overview

XReplicator exposes a Streamable HTTP MCP endpoint from the web UI:

Endpoint: POST /api/mcp
Auth: Authorization: Bearer <api-key>
Requirement: MCP_ENABLED=true and at least one active API key

You can manage MCP settings and API keys in the UI:

Settings -> MCP
Configure MCP_ENABLED, BACKUP_GRPC_ADDRESS, MCP_RPC_TIMEOUT_MS
Create/list/revoke API keys

Server Configuration

Set these in web/frontend/.env.local:


BACKUP_GRPC_ADDRESS=localhost:50051
MCP_ENABLED=true
MCP_RPC_TIMEOUT_MS=15000
MCP_DB_PATH=./data/mcp.db

Available Tools

XReplicator exposes 79 MCP tools spanning backup operations, mount/explore, alerting, cloud sync, and disaster recovery.

Ops Core (backup, snapshots, jobs)

Tool	Purpose
`replicator.health_check`	MCP/web/gRPC health and server metadata
`replicator.get_server_stats`	Aggregate server backup stats
`replicator.list_clients`	List known clients and status
`replicator.get_client_devices`	Get devices for a client hostname
`replicator.list_snapshots`	List snapshots with optional filters
`replicator.get_snapshot`	Get snapshot details by `snapshot_id`
`replicator.get_delete_impact`	Preview deletion impact for a snapshot
`replicator.list_backup_jobs`	List backup jobs with optional filters
`replicator.trigger_backup`	Start backup (`full`, `incremental`, `auto`)
`replicator.control_backup_job`	`pause`, `resume`, or `cancel` a job
`replicator.delete_snapshot`	Delete snapshot (requires `confirm=true`)

Mount and Explore

Tool	Purpose
`replicator.get_partitions`	Partition info for a prepared snapshot device
`replicator.mount_partition`	Mount a partition read-only
`replicator.unmount_partition`	Unmount a previously mounted partition
`replicator.detach_device`	Unmount all partitions and detach the loop device
`replicator.explore_snapshot`	Browse files/directories within a mounted partition

Alerts

Tool	Purpose
`replicator.list_alert_policies` / `get_alert_policy` / `create_alert_policy` / `update_alert_policy` / `delete_alert_policy`	Manage alert policies (delete requires `confirm=true`)
`replicator.list_recipient_groups` / `get_recipient_group` / `create_recipient_group` / `update_recipient_group` / `delete_recipient_group`	Manage email recipient groups (delete requires `confirm=true`)
`replicator.list_webhook_endpoints` / `get_webhook_endpoint` / `create_webhook_endpoint` / `update_webhook_endpoint` / `delete_webhook_endpoint`	Manage webhook endpoints (delete requires `confirm=true`)
`replicator.list_device_alert_policies` / `get_device_alert_policy` / `assign_policy_to_device` / `remove_device_policy`	Manage device-to-policy assignments
`replicator.list_alert_events`	Alert event history and delivery status
`replicator.send_test_notification`	Send a test alert notification

Cloud

Tool	Purpose
`replicator.get_cloud_config`	Get cloud sync + compaction configuration
`replicator.update_cloud_config`	Update cloud configuration (optimistic concurrency via `expected_revision`)
`replicator.list_cloud_snapshots`	List snapshots stored in cloud storage
`replicator.get_cloud_snapshot`	Get a single cloud snapshot

Disaster Recovery

Tool	Purpose
`replicator.list_dr_sources` / `list_dr_attached_disks`	Inspect DR-staged sources and attached disks
`replicator.set_dr_source_policy`	Enable/disable DR staging for a source (requires `confirm=true`)
`replicator.retry_dr_backfill`	Retry a stalled DR backfill
`replicator.run_dr_precheck`	Check blueprint readiness for failover
`replicator.trigger_dr_failover`	Execute failover for a blueprint (requires `confirm=true`, high blast radius)
`replicator.get_dr_failover_history`	List past failover operations
`replicator.prepare_dr_failback` / `check_dr_failback_disks` / `start_dr_failback_sync`	Prepare and sync a failback operation
`replicator.cutover_dr_failback`	Cut production traffic back to the primary site (requires `confirm=true`, high blast radius)
`replicator.control_dr_failback`	Pause/resume/stop a failback (`stop` requires `confirm=true`)
`replicator.get_dr_failback_status` / `get_dr_failback_history`	Failback status and history

DR Blueprints and Targets

Local workflow configuration (no gRPC call to the backup server) so an agent can drive DR end-to-end: blueprint → targets → precheck → failover → failback.

Tool	Purpose
`replicator.list_dr_blueprints` / `get_dr_blueprint` / `create_dr_blueprint` / `update_dr_blueprint` / `delete_dr_blueprint`	Manage DR blueprints
`replicator.list_dr_blueprint_rows` / `upsert_dr_blueprint_row` / `delete_dr_blueprint_row`	Manage per-VM source-to-target rows
`replicator.list_dr_targets` / `get_dr_target` / `create_dr_target` / `update_dr_target` / `delete_dr_target`	Manage DR cloud targets (AWS/Azure/GCP); secrets are redacted on read

Misc

Tool	Purpose
`replicator.list_cron_jobs` / `set_cron_job` / `trigger_cron_job`	Manage and trigger cloud-sync/compaction schedules
`replicator.get_operation_status` / `list_operation_history`	Track cloud-sync/compaction operations
`replicator.get_license_status`	Current license status and entitlements
`replicator.get_client_stats` / `get_device_stats`	Lightweight client and device statistics
`replicator.get_resume_point`	Checkpoint info for resuming an interrupted backup
`replicator.get_incremental_backup_info`	Dirty-block and app-aware tracking stats
`replicator.get_export_progress`	Progress of an in-flight raw image export

Guardrails:

confirm=true is required for: delete_snapshot, delete_alert_policy, delete_recipient_group, delete_webhook_endpoint, set_dr_source_policy, trigger_dr_failover, cutover_dr_failback, and control_dr_failback (only when action="stop")
update_cloud_config uses optimistic concurrency (expected_revision) instead of confirm
RPC requests are bounded by MCP_RPC_TIMEOUT_MS
Excluded by design: streaming/byte-transfer operations (cloud restore, mount progress, partition restore, file download) and cloud provider resource-discovery dropdowns (AWS/Azure/GCP regions, VPCs, instance types)

Client Setup

For remote MCP over HTTP, use mcp-remote and pass the bearer token via MCP_REMOTE_AUTHORIZATION.

Claude Desktop

Config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json


{
  "mcpServers": {
    "xreplicator": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<your-host>/api/mcp"],
      "env": {
        "MCP_REMOTE_AUTHORIZATION": "Bearer <your-api-key>"
      }
    }
  }
}

Restart Claude Desktop after updating the config.

Codex

Config file:

~/.codex/config.toml


[mcp_servers.xreplicator]
command = "npx"
args = ["-y", "mcp-remote", "https://<your-host>/api/mcp"]
enabled = true
 
[mcp_servers.xreplicator.env]
MCP_REMOTE_AUTHORIZATION = "Bearer <your-api-key>"

VS Code and other MCP JSON clients

Workspace config file:

.vscode/mcp.json


{
  "mcpServers": {
    "xreplicator": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<your-host>/api/mcp"],
      "env": {
        "MCP_REMOTE_AUTHORIZATION": "Bearer <your-api-key>"
      }
    }
  }
}

This same mcpServers JSON structure also works for other compatible MCP clients (for example, Cursor with .cursor/mcp.json).

Validation Checklist

Enable MCP in Settings -> MCP
Create an API key and use it in client config
Confirm BACKUP_GRPC_ADDRESS points to your running backup server
In your MCP client, run replicator.health_check
If health is good, run replicator.list_clients