Skip to content
PerSQL PerSQL PerSQL

Agent quickstart

PerSQL gives every AI agent its own SQLite database, isolated and reachable over HTTP. The same surface that powers query also exposes the primitives that make agents tractable: one-shot sandboxes per task, pre-flighted writes, and a replayable action log.

Three ways to connect, in order of recommendation:

  1. MCP — for any Model Context Protocol–aware runtime (Claude Desktop, Cursor, Cline, Continue, etc.). One config block, typed tools, no code.
  2. SDK — @persql/sdk for TypeScript / Node, with db.asTool() for Anthropic + OpenAI function calling.
  3. Raw HTTP — for any language, anywhere.

1. Get a database

Section titled “1. Get a database”

Sign in at console.persql.com. On first login PerSQL auto-provisions a workspace named after your handle plus a database called main — you don’t need to copy a token. MCP runtimes negotiate their own access via OAuth (next step). The CLI and any direct HTTP caller can still mint a long-lived token from API tokens → New token; the Connect tab has paste-ready snippets for every option.

Section titled “2a. MCP (recommended for agent runtimes)”

Add to your MCP config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS for Claude Desktop, ~/.cursor/mcp.json for Cursor) — just the URL, no token:

{
  "mcpServers": {
    "persql": {
      "url": "https://mcp.persql.com"
    }
  }
}

The first time your runtime connects, PerSQL responds 401 with an OAuth discovery URL. The runtime opens your browser to console.persql.com/oauth-consent, you pick which namespace to grant access to, and the runtime stores the issued token automatically. No copy-paste step. Tested with Claude Desktop, Cursor, and Cline; any MCP-spec OAuth 2.1 runtime works.

If your runtime doesn’t support OAuth, fall back to the bearer-token shape:

{
  "mcpServers": {
    "persql": {
      "url": "https://mcp.persql.com",
      "headers": { "Authorization": "Bearer psql_live_…" }
    }
  }
}

The agent now has roughly sixty typed tools spanning six groups:

  • Agent-shape primitives — claim_branch (one-shot sandbox per run), propose_mutation / apply_mutation (review-before-execute), claim_handoff (delegate a scoped token to a sub-agent), query_log, recent_actions (replay what changed).
  • Query — query, batch, wait_for_changes (long-poll change feed for MCP/JSON-RPC agents that can’t hold a WebSocket), validate_sql, ask (NL→SQL).
  • Schema & docs — describe_database, search_schema, schema_doctor, list_tables, describe_table, sample_table, set_database_doc / set_table_doc / set_column_doc, get_docs.
  • Branches, snapshots, endpoints — list_branches, create_branch, merge_branch, preview_branch_merge, pin_branch, branch_diff, create_snapshot, restore_to_time, list_endpoints, publish_endpoint, endpoint_logs, plus migrations and saved queries.
  • Provision & self-poke — create_database (spin a new SQLite DB, optionally with a TTL for auto-cleanup), create_schedule / list_schedules / delete_schedule (cron SQL inside the DO), create_webhook / list_webhooks / delete_webhook (outbound HMAC-signed webhooks on table changes).
  • Spend & self-funding — whoami (live balance + in-hour burn rate), topup_balance (mint a Stripe Checkout URL programmatically). When the balance runs out, the 402 response carries an x402-compatible body so an MPP-capable runtime can complete a top-up without a human.

See the MCP guide for the full tool reference and per-runtime config paths.

2b. SDK

Section titled “2b. SDK”
Terminal window
npm i @persql/sdk
import { PerSQL } from "@persql/sdk";


const persql = new PerSQL({ token: process.env.PERSQL_TOKEN! });
const db = persql.database("acme/main");


await db.query(
  "CREATE TABLE IF NOT EXISTS customers (id INTEGER PRIMARY KEY, email TEXT)"
);
await db.query(
  "INSERT INTO customers (email) VALUES (?)",
  ["me@example.com"]
);


const { data } = await db.query<{ id: number; email: string }>(
  "SELECT id, email FROM customers"
);
console.log(data);
// → [{ id: 1, email: "me@example.com" }]

Hand the database directly to Claude or GPT as a tool:

const tool = db.asTool().anthropic;   // or .openai
// pass `tool` in `tools: [...]` and call `db.runTool(input)` on each tool_use.

2c. Raw HTTP

Section titled “2c. Raw HTTP”
Terminal window
curl -X POST https://api.persql.com/v1/db/acme/main/query \
  -H "Authorization: Bearer psql_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT id, email FROM customers WHERE id = ?","params":[1]}'

What’s next

Section titled “What’s next”

The recipes are the shortest path from “I have a token” to “my agent does the thing”:

  • Per-agent sandbox — a fresh DB or branch per agent run, idempotent on a ref, auto-deleting on a TTL. No per-branch fee.
  • Sub-agent handoff — delegate a scoped, single-use token to a sub-agent.
  • Cost-aware loop — self-throttle on meta.costUsd returned in every response.
  • PR-preview DB — one idempotent branch per pull request, auto-clean on close.

Reference: