<!-- Source: https://dev.dbmigratepro.com/docs/ai-agents -->

# AI agents

DBMigratePro is built to be operated by AI agents, not just humans. There are two integration
paths, and both authenticate with a personal API token (**Settings → API Tokens**), scoped to that
token's user:

- **MCP** (Model Context Protocol) — connect an MCP-capable client to the migrations server and
  call typed tools.
- **REST API** — drive the same [Migrations API](/docs/migrations-api) from any language or agent
  framework with a bearer token.

## MCP

Point your MCP client at the migrations server:

```
POST https://dev.dbmigratepro.com/mcp-migrations
Authorization: Bearer YOUR_TOKEN
```

**Copy-paste configuration for Claude Code, Claude Desktop, Cursor, VS Code, Zed and Windsurf is on
[Connect an AI assistant](/docs/mcp-setup)** — start there if you just want it working.

MCP is self-describing — on connect, the client discovers each tool's exact name and input schema.
The server advertises:

| Tool | What it does |
|---|---|
| `list-migrations-tool` | List the user's migrations (id, status, type, size, cost). |
| `get-migration-tool` | Full detail for one migration by id, plus recent log lines. |
| `preview-migration-tool` | Pre-flight a source/target pair — reachability, size, transfer vs. conversion, price — without creating anything. |
| `prepare-migration-tool` | Create a migration from a preview. Never charges; if a payment hold is due it returns a checkout link for the user to authorize. |
| `retry-migration-tool` | Re-queue a failed migration by id. |
| `reset-migration-tool` | Clean and re-run a migration by id. |
| `delete-migration-tool` | Delete a migration by id (irreversible — confirm first). |

Every call is scoped to the token's account, so an agent only ever sees and touches that user's
migrations.

> `prepare-migration-tool` never completes payment on the agent's behalf. When a **pay-as-you-go**
> run needs a hold, it returns a `checkout_url` for the user to authorize in a browser. **Pro** and
> **first-migration-free** runs start with no payment step.

## REST API

If your framework doesn't speak MCP, the REST API is identical in capability — the agent sends
`Authorization: Bearer <token>` on every call:

1. **Create the migration.** `POST /api/migrations` with the source and target URLs.
2. **Handle payment.**
   - **Pro** or **first-migration-free**: the response has no `checkout_url` — the run is already
     going. Skip to step 3.
   - Otherwise the response has a `checkout_url`. An agent **cannot** complete payment itself —
     surface the `checkout_url` to the user to authorize the hold; the migration starts
     automatically once they do.
3. **Poll for completion.** `GET /api/migrations/{id}` until `status` is `completed` or `failed`.
   Report the result (and, on failure, the `logs`) back to the user.

See the full [Migrations API](/docs/migrations-api) for every endpoint and response shape, or point a
generic agent framework at [`/openapi.json`](/openapi.json) — a machine-readable description of every
endpoint, its authentication, and its rate-limit tier, generated from the live route table.

## Guidance for agents

- **Never invent connection URLs.** Ask the user for the exact source and target URLs.
- **Never try to bypass payment.** If a `checkout_url` comes back, the user must authorize it.
  You're only charged on success, so it's safe to tell the user that.
- **Treat `failed` as retryable.** Read the migration `logs`, explain the cause, and offer to
  retry once the underlying issue is resolved.
- **Confirm before deleting.** Deletion is irreversible.