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

Ops Core tools currently exposed by the MCP server:

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`)

Guardrails:

replicator.delete_snapshot requires explicit confirm=true
RPC requests are bounded by MCP_RPC_TIMEOUT_MS

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