Synapsor Runner

Stop giving AI agents execute_sql. Give them reviewed business actions.

Synapsor Runner is an open-source, local-first MCP runtime for Postgres and MySQL. It exposes semantic tools such as billing.inspect_invoice and billing.propose_late_fee_waiver, saves risky changes as proposals, and keeps database credentials, approval, and writeback outside the model-facing tool surface.

Prove It In 60 Seconds

The path is: audit your existing MCP risk, then demo the safety boundary, then connect a staging database. The first two commands finish in seconds and touch nothing but a local fixture file.

First, inspect the risk in a typical raw-SQL database MCP server. This works even if you never adopt Runner:

npx -y @synapsor/runner audit --example dangerous-db-mcp

Then see the proposal, approval boundary, evidence, and replay loop. It needs no database, Docker, config file, MCP client, or Synapsor account:

npx -y @synapsor/runner demo --quick

The quick demo creates a fixture ledger at ./.synapsor/quick-demo.db. It teaches the boundary; it does not claim to test your database connection.

Safety Model

AI agent or MCP client
        |
        | reviewed semantic tool
        v
+--------------------------------+
| Synapsor Runner MCP            |
| trusted tenant/principal scope |
| evidence + query audit         |
| proposals, not direct writes   |
+--------------------------------+
        |
        | scoped read / approved guarded writeback
        v
+--------------------------------+
| Your Postgres or MySQL         |
| source of truth                |
+--------------------------------+

Local SQLite ledger:
evidence -> proposal -> approval -> receipt -> replay

The model can inspect scoped data and propose an exact change. It cannot call approval or apply tools. A human or trusted operator approves outside MCP, then Runner either performs one guarded row update or routes the approved proposal to an app-owned executor.

Connect A Staging Database

Start with a staging or disposable database and a read-only credential. Keep database permissions, restricted views, and row-level security in place.

npm install -g @synapsor/runner
export DATABASE_URL="postgresql://runner_reader:REPLACE_ME@db.example.com:5432/app?sslmode=require"
synapsor-runner start --from-env DATABASE_URL --schema public

The guided command inspects metadata, asks you to choose one table or view, creates trusted context, generates reviewed capabilities, previews the MCP tool surface, and prints the next smoke and serve commands. It stores environment variable names, not connection strings.

The interesting part of the generated configuration is the capability entry: a reviewed, tenant-scoped read with an explicit column allowlist and required evidence. The storage, source, and trusted-context wiring around it (including statement timeouts) is generated for you; the full file is in the own-database guide.

{
  "name": "billing.inspect_invoice",
  "kind": "read",
  "source": "app_postgres",
  "target": {
    "schema": "public",
    "table": "invoices",
    "primary_key": "id",
    "tenant_key": "tenant_id"
  },
  "args": {
    "invoice_id": { "type": "string", "required": true, "max_length": 128 }
  },
  "lookup": { "id_from_arg": "invoice_id" },
  "visible_columns": ["id", "tenant_id", "status", "late_fee_cents", "updated_at"],
  "evidence": "required",
  "max_rows": 1
}

Set the trusted values in the process that launches Runner, then validate and preview the exact model-facing boundary before connecting an MCP client:

export SYNAPSOR_TENANT_ID="acme"
export SYNAPSOR_PRINCIPAL="local-developer"
synapsor-runner config validate --config ./synapsor.runner.json
synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db

For proposal capabilities and writes, follow the complete own-database guide. One-row updates can use Runner's guarded direct writeback. Inserts, multiple tables, or external effects go through an app-owned executor after approval.

Trust And Verification

Start with the Threat Model. It defines protected assets, trust boundaries, covered threats, non-goals, and required operator controls.

• Conformance fixtures prove trusted context, scoped reads, kept-out fields, proposal boundaries, approval, receipts, and replay behavior rather than only validating JSON shape.
• corepack pnpm test:live-apply runs disposable Postgres and MySQL scenarios. It proves source rows stay unchanged before approval, guarded writeback applies once, idempotent retry does not duplicate the effect, and a stale row returns a conflict.
• The C++/Cloud round-trip verifier exports normalized contracts, validates them with @synapsor/spec, and loads them in Runner. The shared contract and verification commands are documented in Conformance.

Runner is a narrow agent/database safety boundary, not a replacement for least-privilege database access, host security, or application authorization. See Security Boundary and Current Limitations.

Packages

Runner executes locally. The spec is the portable contract shared by Runner and Cloud/C++. The DSL gives that contract a reviewable source format. Start with Capability Authoring. Use .synapsor.sql for DSL source files when you want editors to provide generic SQL highlighting; legacy .synapsor files remain supported and produce the same contract JSON.

OSS And Cloud

Synapsor Runner works by itself for local and single-node deployments: your database remains the source of truth and the local SQLite ledger stores review artifacts. Synapsor Cloud adds a shared contract registry, immutable versions, downloadable Runner bundles, and team activity, evidence, and approval surfaces. See OSS Runner vs Synapsor Cloud for the detailed boundary.

Next Steps

• Run the support-plan-credit flagship example.
• Connect Claude, Cursor, OpenAI Agents SDK, or another MCP client.
• Author and push a validated contract to Cloud.
• Browse the task-first documentation index.
• Report bugs or request features through GitHub Issues.

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.

Maintainer and contributor workflows live in CONTRIBUTING.md and AGENTS.md.