SQLite MCP Sidecar

sqlite-sidecar-mcp

An agent-safe MCP sidecar for one live SQLite database.

It gives an AI agent controlled access to a database that another application already owns, and it limits the damage that an authorized but mistaken agent can cause.

[][ci-url] [][license-url] [][ghcr-url] [][dotnet-url]

Contents

• About the project
• Built with
• Getting started
• The eight tools
• Permissions
• Configuration
• Deployment
• Security
• Contributing
• License
• Contact
• Acknowledgments

About the project

An application owns a SQLite file. You want an agent to read it, and perhaps to change a few rows. Handing the agent a SQL connection gives it the whole file and one DELETE with a wrong predicate is unrecoverable. sqlite-sidecar-mcp sits next to that application as one more SQLite client and speaks MCP over HTTP. The owning application does not change.

It runs in production next to the MCP Canary API, where it gives the operator's coding agent read-only access to the live database.

flowchart TD

agent[AI / MCP client] -->|HTTPS| proxy[Reverse proxy] proxy -->|private HTTP| sidecar[sqlite-sidecar-mcp] sidecar -->|SQLite client| db[(app.db)] app[Owning application] -->|SQLite client| db

The product defends against two callers. One is an unauthorized client, which the token and the request budget stop. The other is an authorized client that makes a mistake, and that one is the unusual part: an agent with permission to write can still write the wrong thing. Structured writes, a mandatory predicate, a row limit that counts cascades, and a per-minute write budget exist for it.

[!IMPORTANT]

One sidecar process serves one database. The request budget, the write budget and the

idempotency cache live in process memory. A second replica gives you two independent budgets and

two independent caches, and nothing reports it. Do not scale this service. Run a second sidecar

only for a *different* database or a *different* trust boundary.

Built with

• .NET 10, ASP.NET Core
• Model Context Protocol over Streamable HTTP
• Microsoft.Data.Sqlite with the bundled native SQLite
• TOON for row output, which costs fewer tokens than JSON

( back to top )

Getting started

Prerequisites

• Docker
• A SQLite database that already exists. The sidecar never creates one: creation would hide a wrong path and leave an empty database next to the real one.

Run it

docker run -d --name sqlite-sidecar \

-p 127.0.0.1:8080:8080 \ -v /srv/myapp/data:/data \ -e SQLITE_SIDECAR_DB=/data/app.db \ -e SQLITE_SIDECAR_TOKEN=' ' \ -e SQLITE_SIDECAR_PERMISSIONS=schema,read \ --read-only --tmpfs /tmp \ --cap-drop=ALL --security-opt=no-new-privileges \ ghcr.io/xakpc/sqlite-mcp-sidecar:latest

The mount must be writable, also for the read-only permission set above. SQLite opens the -shm file read-write for a read-only connection to a WAL database, and a read-only mount fails in a way that reads like a permission fault rather than a configuration mistake.

Connect an agent

The endpoint is /db/mcp and the token goes in an Authorization header:

{

"mcpServers": { "app-database": { "url": "https://example.com/db/mcp", "headers": { "Authorization": "Bearer " } } } }

There is no OAuth. A client that insists on OAuth discovery finds no resource metadata on a 401 and stops; the expected consumer is one agent that an operator configured with a static header.

Generate a token and an environment block

dotnet run scripts/token.cs

It asks for the deployment shape, mints a token from a cryptographic random source, repairs a permission set that would fail startup, and prints the block as .env, shell or compose.

( back to top )

The eight tools

Which tools exist is decided by the permission set. A tool the deployment does not cover is absent from tools/list — it does not appear and then fail.

A query answers in TOON, which is a compact tabular text:

rows[2]{id,status}:

54,done 41,failed

truncated: false

truncated: true means a limit stopped the read, not that the query failed.

Structured writes

update and delete take a flat filter, never SQL. Every condition joins with AND; there is no or and no nesting. A disjunction is one call per branch, and that is the tighter bound: each call is pre-counted and limited on its own, while one or call would pool the blast radius of every branch into a single maxRows.

maxRows counts every row the write changes — rows removed by ON DELETE CASCADE and rows a trigger writes included. A delete with maxRows: 1 cannot quietly destroy a cascade subtree and report one row. A filter that matches too many rows is rejected *before* the write starts, and a write that turns out to exceed the limit is rolled back.

Every write tool takes a mandatory requestId. The same requestId returns the stored response of a committed write instead of applying it twice. Failures are not cached, so a retry after a failure is a real retry.

( back to top )

Permissions

One deployment has one token and one permission set. A permission is a property of the deployment, not of a user — there are no users, roles or ACLs. Separate trust levels use separate deployments, which keeps the boundary visible in the deployment configuration.

SQLITE_SIDECAR_PERMISSIONS=schema,read      # the default

The name danger-raw-write is deliberately alarming. A neutral name would hide the cost.

[!WARNING]

A permission applies to every table in the database. There is no table allowlist and no column

allowlist. write does not protect one table from an agent that has write. If a table must stay

untouched, it belongs in a different database with a different sidecar.

Two rules the sidecar enforces at startup, so a mistake is a failed start and not a surprise later:

• The read floor. write and danger-raw-write are only valid together with schema and read. A structured write validates names against the live schema, so an agent that cannot call schema would be guessing. The missing permissions are never added silently, because that would make SQLITE_SIDECAR_PERMISSIONS an untrue record of the deployment.
• No unknown names. SQLITE_SIDECAR_PERMISSIONS=reed fails startup instead of quietly granting less than the operator believes.

No permission grants another. read does not imply write, and danger-raw-write is independent of write.

( back to top )

Configuration

Every value is an environment variable with the SQLITE_SIDECAR_ prefix. Startup fails when a value is absent or invalid, and it reports every problem at once. The sidecar does not start in a degraded state.

Required:

Optional, with defaults

ASP.NET Core settings that matter: ASPNETCORE_URLS (the image sets http://0.0.0.0:8080) and ASPNETCORE_ENVIRONMENT. Outside Development the sidecar logs JSON, which is what a container log pipeline wants.

The effective write limit is min(the caller's maxRows, SQLITE_SIDECAR_MAX_WRITE_ROWS), so an agent can ask for less but never for more.

Paths

/health reports that the process is alive and nothing else. It never touches the database: a probe runs every few seconds, and an expensive probe would become a denial-of-service vector against the owning application. The checks that do need the file run once, at startup.

( back to top )

Deployment

[!CAUTION]

The proxy must not strip the `/db` prefix. /db/mcp is the whole public path: the sidecar

routes the same URL the agent calls. Both Kamal and Coolify strip a matched prefix *by default*,

and a stripped prefix produces a 404 that reads like a broken server. Every recipe below turns

stripping off.

Common to all of them: one replica, /data writable even for schema,read, and the container port never published to the internet — the reverse proxy is the only way in, and it is also what matches the Host header. The sidecar does no host filtering of its own.

Docker Compose

services:

app: image: my-app volumes:

• sqlite-data:/data

sqlite-sidecar: image: ghcr.io/xakpc/sqlite-mcp-sidecar:latest deploy: replicas: 1 e