All docs
Docs
Getting Started

Choose the smallest safe database boundary

Use direct read-only access or a hand-built tool when it is sufficient; add Runner when you need a shared reviewed action, approval, receipt, and replay boundary.

Overview

You do not always need Synapsor Runner. For disposable local data, a direct database MCP server may be appropriate. For trusted exploration, a database role restricted to the exact permitted rows and columns may be enough. For one or two stable operations, a fixed application endpoint or stored procedure may be the simplest safe answer.

Runner becomes useful when consequential reads or writes need the same portable trust mechanics across agents or teams: trusted scope outside model input, explicit visible and kept-out fields, exact proposals before mutation, approval outside MCP, guarded apply, idempotency receipts, and replay.

Runner governs only traffic that passes through reviewed capabilities. It does not prevent prompt injection, secure a second raw tool, replace database authorization, provide backups, or make a deployment compliant. Keep least-privilege roles, RLS or restricted views, encryption, monitoring, application authorization, and tested recovery underneath it.

When each approach is enough

Direct raw database MCP is for synthetic, disposable, or deliberately developer-privileged environments. Read-only database access is sufficient when database policy already limits the credential to exactly the rows and fields the agent may see, query cost is bounded, and no review lifecycle is required.

A hand-built application tool is often best for a few stable operations when one team owns trusted scope, validation, retries, conflicts, approvals, receipts, and investigation. Rich external effects and multi-table transactions should remain app-owned even when Runner carries the approved proposal to that handler.

Use Runner when the model should receive semantic capabilities rather than SQL and you need exact Data PRs, explicit activation, approval outside the agent, guarded commit, durable receipts, and replay through one reviewed contract.

Keep the database floor

A shared database credential with application-level predicates is only as strong as the Runner process and its scope implementation. Harden PostgreSQL deployments with transaction-bound RLS where possible. For MySQL, use restricted views, per-tenant credentials, or isolated deployments when stronger tenant separation is required.

Backups, disaster recovery, network policy, credential rotation, least privilege, and independent authorization tests remain operator responsibilities in every approach.

Developer notes

  • Identify who chooses SQL, tenant scope, fields, predicates, approval, and commit timing.
  • Keep direct read-only access when the database itself already provides the complete required boundary.
  • Keep a narrow app-owned endpoint when its existing safety and evidence guarantees are sufficient.
  • Evaluate Runner on one consequential staging action when a shared review and commit boundary is needed.
  • Retain database RLS or restricted views, least-privilege roles, monitoring, and tested backups.