Synapsor Runner

Database authority for AI agents.

Let agents query and propose changes to Postgres/MySQL without giving the model SQL or commit authority.

MCP connects the agent. A reviewed Synapsor boundary controls database access and commit.

Synapsor Runner is an open-source database-authority layer between an AI agent and Postgres/MySQL. You review its tables, fields, relationships, operations, and limits. Agents may explore within it or create exact proposals; activation, approval, and commit stay outside model-facing tools.

Agent sees       reviewed grammar, tools, bounded results, proposals
Agent never gets raw SQL, credentials, trusted scope, activation, approval, or commit
Runner handles   plan validation, scope injection, direct-write rechecks, receipts
Outside model    humans control access/rollout; humans or policy approve proposals

The authority path is Explore -> Protect -> Propose -> outside-model decision -> Commit -> Receipt, without falling back to execute_sql.

Read Database Authority And Application Guardrails, or start with safe Postgres MCP, prevent arbitrary LLM SQL, or human approval for agent writes.

Start With Your Database

Use a SELECT-only, non-owner development or staging credential:

npx -y @synapsor/runner start --cli

The first command needs no install. Later examples use a global install:

npm install --global @synapsor/runner

Otherwise use npx -y @synapsor/runner.

Paste the URL into the hidden prompt or export DATABASE_URL. Runner first inspects schema metadata, not source rows. It proposes conservative read access that grants the agent nothing until you review and activate it. You do not need to write DSL or JSON to begin.

To use the preview Workbench instead:

synapsor-runner start --from-env DATABASE_URL

For automation, run synapsor-runner onboard --help; missing decisions are reported together.

Review the conservative starting boundary, then press Enter to activate it. Use M to choose OpenAI, Anthropic, or a loopback model, and E to change tables or field access. Runner asks permission before reviewed visible data can leave the machine. Every access change remains disabled until a human confirms it.

See Database To First Safe Tool.

Interface status: Prefer the CLI. Workbench is preview; production Streamable HTTP MCP is not.

Related MCP server: mysql-mcp

Ask A Useful Question

After review, use either of these paths. Both call the same validation and execution code and receive no more authority than the reviewed boundary.

Use the preferred terminal Ask or the preview Workbench. Supply your own OpenAI or Anthropic key, or use a loopback OpenAI-compatible model. Keys and conversation history stay in memory. A loopback model keeps provider traffic on the machine.

synapsor-runner try ask --provider openai --model gpt-5-mini

Use an MCP client that already has a model. Runner can prepare project-local configuration without putting database credentials in the client file:

synapsor-runner mcp install \
  <cursor|claude-code|claude-desktop|vscode|generic-stdio> \
  --project --authoring --project-root . --yes

See Client Recipes for supported MCP hosts.

Local development/staging Explore exposes only:

app.describe_data
app.explore_data

Agents receive reviewed operations, never SQL. They can combine reviewed totals, distinct counts, dimensions, filters, comparisons, time buckets, Runner-resolved relative UTC windows, top-N rankings, and many-to-one relationships. Every plan is scope-injected, read-only, budget-bounded, and small-cohort suppressed.

Question
Which reviewed regions contributed most to failed payments last week?

Runner-verified result
region       failed_payments
west         184
north        121

1 additional group and its label were withheld below the reviewed cohort minimum.

When a question crosses the boundary, refusal is the result:

REFUSED
The requested customer relationship is proven by the schema but has not been reviewed.
No source query executed.

The model cannot activate the offered review path. Normal answers keep model interpretation separate from Runner-rendered facts; /details shows the exact typed request, validated plan, runtime checks, suppression, and evidence.

Explore is local by default. Production opt-in over secured Streamable HTTP requires verified JWT scope, per-principal and tenant budgets, rate limits, and atomic shared-Postgres accounting. See Production Scoped Explore Over HTTP and Explore And Protect.

Turn A Useful Question Into Production Access

After an answer proves useful, run /protect. Runner freezes that one successful analysis into a named read-only capability with generated DSL, canonical JSON, tests, and provenance. It starts disabled.

The CLI and Workbench show the same review and require a separate human activation. No browser or copied digest is required in the CLI; changed artifacts fail closed. The model cannot invoke Protect or activation.

/details A2 --sql can show an operator-only parameterized statement with all values redacted. SQL never reaches the model, MCP response, or durable evidence.

For fixed production question shapes, switch the selected project client from temporary Explore to the activated named capability:

CLIENT=claude-code # or cursor / vscode
synapsor-runner mcp install "$CLIENT" --project \
  --config ./synapsor.runner.json \
  --store ./.synapsor/local.db \
  --yes

Protected capabilities remain the narrowest production choice. For reviewed ad-hoc analytics, synapsor-runner config init --production-explore generates secured runtime config from the boundary without secrets.

Let Agents Propose Bounded Changes

For writes, describe one business action. Runner generates an inert TypeScript draft; it does not silently add a tool or change active authority:

synapsor-runner start \
  --action plan_credit \
  --description "Propose one reviewed customer plan credit" \
  --based-on support.inspect_customer

After a human reviews and activates that action, the agent can create an exact proposal, sometimes called a Data PR. It still cannot approve or apply it:

Proposal  support.propose_plan_credit on CUS-3001
Effect    plan_credit_cents: 0 -> 2500
Database  unchanged until an outside-model decision

Humans do not need to approve every routine request. A team can review a policy once so low-risk requests inside fixed value, rate, and scope limits are policy-approved. Automatic application still requires a separate deployment opt-in and a trusted worker that repeats every guard. Exceptions wait for a person.

Auto-approval does not mean auto-apply: the exact contract digest and deployment both opt into supervised execution. External notifications are disabled and quiet by default. A webhook response cannot approve or apply.

Immediately before a Runner-managed commit, live scope, evidence freshness, version, bounds, limits, and idempotency are rechecked. Drift causes no mutation. See Supervised Apply, Proposal Freshness, and Verified Operator Identity.

Other Ways To Start

See The Guardrails Without A Database

Run a complete guarded-write proof with no database, Docker, MCP client, model, account, or configuration:

npx -y @synapsor/runner try --prove

The embedded fixture demonstrates an exact proposal, outside-model approval, one guarded mutation, a durable receipt, restart-safe retry, and stale-write refusal. It proves Runner's local mechanics, not a live database connection. Temporary proof state stays project-local under ./.synapsor/try/. demo --quick remains a noninteractive compatibility alias.

Audit An Existing MCP Server

Already have database MCP tools? Inspect a manifest, remote tools/list, or stdio server without invoking its business tools:

npx -y @synapsor/runner audit --example dangerous-db-mcp
synapsor-runner audit ./tools-list.json

The audit flags raw SQL, arbitrary identifiers, model-controlled authority, and model-facing write execution. See MCP Audit.

Keep Your Existing Service Layer

If your application already exposes narrow authenticated business operations, keep them. Runner can add the agent-specific review, proposal, policy, approval, evidence, receipt, and replay lifecycle around those operations. Multi-step transactions and external effects remain in an application-owned executor. See Application Guardrails.

Why Not Raw Text-To-SQL?

Text-to-SQL can produce confident, plausible, wrong answers while holding much more authority than the question requires. A published ReFoRCE pipeline reports about 11% execution accuracy on the enterprise-scale BEAVER benchmark. In EntSQL, 54.6% of 982 observed failures were wrong filters.

These benchmark-specific figures are not a Runner accuracy claim. Runner cannot decide what a business term means. It removes arbitrary SQL authority, limits the legal plan space, injects trusted scope, and records what was actually validated and executed.

Safety Model

Reviewed capabilities fix context, fields, relationships, operations, bounds, and approval rules. Model-facing tools may inspect bounded data or create exact proposals, but they cannot activate access, choose tenant/principal scope, approve, apply, or revert. Runner does not make a raw-SQL client safe.

Choose application scope, PostgreSQL RLS, or tenant-bound credentials for your threat model; Runner does not replace database permissions. Stdio opens no socket. Network MCP requires authenticated encrypted transport and verified session context. See Threat Model, Database Scope, and HTTP MCP.

You May Not Need Runner

A read-only account or a few fixed low-risk operations may suffice. Runner is useful when flexible agent questions or multiple tools need one reviewed boundary, writes require outside-model decisions, or integrations need common evidence, retries, conflicts, receipts, and replay.

Trust And Verification

Start with the Security Boundary. Live gates cover scope, mutation, freshness, suppression, and replay. Runner does not replace database or application authorization. Supported sources are PostgreSQL 13-18, full-grammar MySQL 8.0.16+, and limited-tier MySQL 8.0.11-8.0.15 or 5.7. Unsupported grammar is hidden before model discovery. See Database Server Compatibility.

Runner uses SQLite or a Postgres ledger. Synapsor Cloud adds registry, approval, jobs, and redacted activity; credentials and execution stay local. Browse Capability Authoring, OSS vs Cloud, or the documentation index.

License

Synapsor Runner is open source under the Apache License 2.0 (Apache-2.0). See Licensing and Trademarks. Synapsor Cloud and proprietary Synapsor platform components are outside this repository.

Contributor workflows live in CONTRIBUTING.md.