Datavor Documentation.

Quick Start

Three steps to your first sync. Total time: 60 seconds.

# Optional — pre-warm the cache so the first call is instant
npx -y datavor@latest --version

{
  "mcpServers": {
    "datavor": {
      "command": "npx",
      "args": ["-y", "datavor"]
    }
  }
}

Configuration

Datavor reads three things in order: environment variables, then a config file at ~/.datavor/config.json, then defaults.

Environment variables

CLI flags

The 47 MCP Tools

Every Datavor capability is exposed as an MCP tool. Grouped here by purpose. AI agents calling these through API keys are billed per tool tier — see Agent Pricing.

Connections (7)

Open and close database connections. One connect_* tool per supported engine, all returning a connection ID that subsequent calls reference.

Example — connect_postgres

{
  "host": "db.acme.com",
  "port": 5432,
  "database": "production",
  "user": "datavor",
  "password": "********",
  "name": "prod-pg"
}

Schema & Discovery (7)

Inspect what's in a database. These are read-only metadata tools — they don't read row data, just structure.

Sync (6)

Move data between connected databases. Sync calls are the only tools that actually transfer rows.

Change Data Capture (3)

Real-time replication driven by Postgres WAL or MySQL binlog. CDC tools start a persistent stream — the connection stays open and emits changes as they happen at the source.

Scheduler (8)

Save sync configurations as recurring jobs with optional dependencies. Jobs run on a cron schedule and can wait for upstream jobs to finish first.

Context Engine (11)

The persistent local SQLite knowledge store that makes Datavor smart over time. Rules, recipes, suggestions, and learned errors all live here.

Dashboard (3)

Aggregate views for the Web UI and for AI-driven status checks.

Pro Licensing (2)

New in v3.1. Lets users register for and activate a Pro license from inside their AI tool — no separate website signup. See Pro Licensing for details.

Web UI v3.0+

A local React dashboard at localhost:3000 that shows everything Datavor knows. Read-only — Claude still drives writes via MCP.

Start it with:

datavor webui

Or visit http://localhost:3000 directly if Datavor is already running.

What's inside

HTTP Transport v3.0+

Run Datavor as a long-lived HTTP MCP server instead of stdio. Useful for remote MCP clients, containerized deploys, or sharing one Datavor instance across multiple machines.

# Start the HTTP transport on :4747 (default)
datavor serve

# Or specify a port
DATAVOR_HTTP_PORT=8080 datavor serve

The HTTP transport uses Streamable HTTP MCP with bearer-token auth, session management, and SSE for tool results. Connect by pointing your MCP client at http://<host>:4747/mcp.

Pro Licensing v3.1+

Pro adds a commercial-use license and priority support. Every feature in Datavor is available on Free — Pro is licensing, not feature gating. See Pricing.

register_pro

Initiate Pro signup from inside your AI tool. Returns nothing visible — but you'll receive an email at the address provided with the activation code.

{
  "email": "dev@acme.com",
  "plan": "annual"      // or "monthly"
}

You'll be redirected to Stripe checkout. After payment, the activation code arrives by email within seconds.

activate_pro

Apply the activation code to unlock Pro features on this machine and any other you install Datavor on with the same code.

{
  "code": "dvpro-XXXXXX-XXXXXX-XXXXXX"
}

Equivalent to the CLI: datavor activate dvpro-XXXXXX-XXXXXX-XXXXXX.

Agent Billing API v3.2

For autonomous AI agents calling Datavor through API keys. Metered per tool call, billed in USDC or Stripe. See Agent Pricing for tier rates and the cost model.

Authentication

Every request needs an Authorization: Bearer dvpro_agent_* header. Get an API key at datavor.ai/agent.

curl -X POST https://datavor.ai/mcp/call \
  -H "Authorization: Bearer dvpro_agent_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "sync_table",
    "input": {
      "source": "prod-mysql",
      "target": "analytics-pg",
      "table": "orders"
    }
  }'

Response format

Every tool response includes a billing block alongside the tool result.

{
  "result": { "rows_synced": 12847 },
  "billing": {
    "tier": "heavy",
    "charged_usd": 0.05,
    "balance_usd": 9.32
  }
}

Billing endpoints

Error handling

External Alerting v3.0+

Push pipeline events to Slack or any webhook endpoint. Configure on the Web UI Settings page; delivery is live the moment you save.

Events

Six event types fire alerts. Each carries the relevant context — job name, connection, error detail — in its payload.

Slack delivery

Paste a Slack incoming-webhook URL and Datavor formats events as Slack Block Kit messages — structured, readable, with the event type, affected resource, and detail laid out as blocks rather than a wall of JSON.

Generic webhooks

Any non-Slack URL receives a stable JSON envelope — the same shape for every event type, so you can route it to PagerDuty, a custom handler, or your own logging pipeline without special-casing each event.

{{
  "event": "sync_failure",
  "timestamp": "2026-05-19T02:14:08Z",
  "datavor_version": "3.1.0",
  "data": {{
    // event-specific fields — job name,
    // connection, error detail, etc.
  }}
}}

Telemetry & Privacy

Datavor handles your data. We take that seriously and try to be transparent about exactly what leaves your machine.

Free tier — 100% local

The Free tier sends nothing to Datavor servers. No telemetry, no analytics, no usage pings. The Context Engine SQLite database lives at ~/.datavor/context.db and you can inspect, copy, or delete it any time.

Pro tier — daily license-validation ping

Pro installations send one HTTPS request per day to https://datavor.ai/api/license/heartbeat. The payload contains:

{
  "activation_id": "dvpro-XXXXXX",
  "day": "2026-05-19",
  "fingerprint_hash": "sha256:a1b2...",
  "tool_calls": {
    "light": 47,
    "standard": 12,
    "heavy": 3
  }
}

That's the entire payload. Specifically not included:

• Database hostnames, names, schemas, or table names
• Query content (SQL statements, parameter values, results)
• Row data of any kind
• Connection credentials
• Tool inputs or outputs beyond the per-tier count
• Personally identifiable information beyond the activation_id and a machine fingerprint hash

Why the heartbeat exists

Two reasons:

1. License enforcement. Pro is licensed per-developer. Tool-call patterns help us distinguish legitimate developer workflows from agent traffic that should be on Agent API keys instead. We can't enforce the license without seeing some kind of aggregate signal.
2. Capacity planning. Knowing tier distribution across the user base helps us prioritize what to optimize. A user base hitting Heavy tools 10× more than expected tells us where to invest engineering time.

Opt-out

Set DATAVOR_TELEMETRY=off in your environment to disable the heartbeat. Note: disabling telemetry on Pro is a license-violation by default. If you have a privacy-sensitive deployment (air-gapped, defense, healthcare) and need to run Pro without telemetry, email support@datavor.ai for an offline-licensed variant.

Troubleshooting

The handful of things that go wrong most often, and how to fix them.

"Claude doesn't see Datavor tools"

1. Verify the config file path. On macOS it's ~/Library/Application Support/Claude/claude_desktop_config.json, not ~/.claude/.
2. Validate the JSON. A missing comma or bracket silently disables MCP. Use jq . config.json to check.
3. Restart Claude Desktop completely (Cmd+Q on macOS, not just close the window).
4. Check Claude's developer logs: ~/Library/Logs/Claude/mcp-server-datavor.log.

"MySQL connection refused on localhost"

On macOS, MySQL requires 127.0.0.1 rather than localhost due to socket vs TCP defaults. Try connecting with host: "127.0.0.1" explicitly.

"Postgres connection hangs"

Check your pg_hba.conf allows the connection. If you're connecting to a stale daemon, remove postmaster.pid and restart Postgres.

"Web UI shows blank page"

Port 3000 may be taken by another service. Either stop that service or set DATAVOR_WEBUI_PORT=3001 and try localhost:3001.

"CDC stream stops emitting events"

Most commonly: the source's replication slot filled up. Postgres has a fixed WAL retention; if your CDC consumer falls behind, the slot is dropped. Restart with start_cdc to recreate it. For MySQL, check that binlog_expire_logs_seconds isn't aggressively rotating before you can consume.

FAQ