Snail.MCP.Connector¶
Company databases for agents: MongoDB, SQL Server, PostgreSQL; read-only, writes on approval.
Its tools: docs/reference/tools, written from the server itself. Built on
Snail.Sdk: the rules, the dotnet tool package, publishing into ~/.s3l-mcp, the
shared workflows.
dotnet publish src -c Release -r osx-arm64 -p:SnailMcpInstall=true # ~/.s3l-mcp/Snail.MCP.Connector/current
How it reads¶
The server reads the company's databases for the platform's agents, inside the company's own network. Every read goes
through a database user that can only read; every query — task, source, collection, what was asked, how many rows — is
written into a journal of one JSON-lines file a day in the server's data folder, and an answer whose query could not be
written down is withheld. Pipelines that write or run code ($out, $merge, $function, $accumulator, $where) are
refused, and a join may read only collections the source allows.
A SQL Server or PostgreSQL source is read with connector_query and one SELECT (or WITH … SELECT). The statement is
read with its comments and strings taken out, in the engine's own quoting — a quote inside a quoted name ("a'", and
[a'] on SQL Server), PostgreSQL's E'…' and $$…$$ are read as the database reads them: a second statement, a word
that writes, runs code or ends the transaction (INSERT, UPDATE, DELETE, INTO, EXEC, COPY, SET, COMMIT…),
a PostgreSQL function that reads a table or a query named in a string (table_to_xml, query_to_xml, dblink…) or a
table after FROM/JOIN the source does not allow is refused before the database sees it. On PostgreSQL the statement
then runs as a subquery cut at the rows asked — one statement whatever its text holds, and the database stops at the
limit itself — in a transaction that is READ ONLY and always rolled back; on SQL Server in a transaction that is always
rolled back, the command cancelled once the page is full. The query's seconds are its command timeout.
connector_schema reads the columns from information_schema, three rows as examples, the planner's row estimate and
the indexes; connector_export writes the rows of a SELECT as it does a collection's.
The wall that counts is the read-only user's grants. The rules are a door that answers a model in words it can act
on; no list of words names every function that reads a table by its name, and a statement the rules let through still
reads whatever the user may read. Give the reader SELECT on the tables the source allows, and nothing more — the list
of a source's tables is kept by the database only when its grants say the same:
-- PostgreSQL: the tables the source allows, not ALL TABLES
CREATE ROLE reader LOGIN PASSWORD '…';
GRANT CONNECT ON DATABASE ledger TO reader;
GRANT USAGE ON SCHEMA public TO reader;
GRANT SELECT ON clients, invoices, payments TO reader;
ALTER ROLE reader SET default_transaction_read_only = on;
-- SQL Server, in the database: the same tables; db_datareader only when the source allows every one (*)
CREATE LOGIN reader WITH PASSWORD = '…';
CREATE USER reader FOR LOGIN reader;
GRANT SELECT ON dbo.clients TO reader;
GRANT SELECT ON dbo.invoices TO reader;
GRANT SELECT ON dbo.payments TO reader;
-- the writing user, only when writes are wanted, and only on the tables an agent may change
CREATE ROLE writer LOGIN PASSWORD '…'; -- PostgreSQL
GRANT CONNECT ON DATABASE ledger TO writer;
GRANT USAGE ON SCHEMA public TO writer;
GRANT SELECT, INSERT, UPDATE, DELETE ON invoices, payments TO writer;
Writes¶
A write is proposed, never made at once. connector_propose_write dry-runs it as the read-only user — how many
documents it touches, three of them as they are — and keeps it in the data folder; the agent then calls the platform's
request_write_approval, and the task waits. The stand's owner or an administrator (the right to manage agents) reads the proposal in the dashboard, which takes it from
this server at GET /proposals/{id} and brings the decision to POST /proposals/{id}/decision, both with the
X-Approval-Key header — a key the stand gives the dashboard and no agent. connector_apply then runs an allowed
proposal once, as the writing user, for the task that proposed it, within 7 days. An update or a delete needs a filter;
an update is field operators; one proposal touches at most 1000 documents or rows. Applied to MongoDB, the writing
user reads the ids the filter matches now and writes only those: more than the person allowed, and nothing is written —
the data changed, propose again. Every step — propose, decision, applying, apply — goes into the journal first; a step
the journal cannot hold is not taken. Without APPROVAL_KEY writes are off.
A proposal is pending, then approved or rejected, then applying and applied. It is taken — saved as
applying — under one lock before the database is asked, so two calls at once write it once and two decisions at once
take one; what the write ended in is saved whatever became of the call. A write that failed goes back to approved;
a call cut off during the write leaves the proposal applying, and nothing runs it again until a person looks at the
data.
A SQL table is written the same way, and no SQL an agent wrote is ever run: the filter is columns and values —
{"id": 42}, or $eq, $ne, $gt, $gte, $lt, $lte, $in, $null, all of which must hold — an update is $set
and $inc, an insert is an array of rows, and update_one needs a filter that matches exactly one row. The server
writes the statement itself, every name checked and quoted and every value a parameter (PostgreSQL takes text untyped,
so a date written as "2026-06-01" is read as the column's type). The dry run counts and shows the rows as the
read-only user; the write runs as the writing user in one transaction, rolled back when it would touch more rows than
the person allowed — the data changed since, and it has to be proposed again.
Exports and the journal¶
connector_export writes the rows of a filter, a pipeline or a SELECT into the task's working copy under exports/,
as CSV (UTF-8 with a byte order mark) or an Excel workbook. Its start goes into the journal before any row is read, so
no file of the company's rows reaches the copy unrecorded. The rows are read twice — flattened into a spool file of the
server's temporary folder, then written from it a row at a time — so memory holds the columns, not the rows; the file
appears whole, moved into place. A nested field is a column of its dotted path; past MOST_EXPORT_COLUMNS the rest of a
row's fields go into one column, _more, as JSON. A workbook cell is a number only when the data held a number — the
postal code 08001 stays text — and a CSV cell of text that a spreadsheet would run as a formula (=, +, -, @)
starts with an apostrophe.
An export is a job of its task (Snail.Sdk.Mcp.Hosting jobs): it is checked and begun in the journal while the call is
served, and its rows are written by the job. The call takes wait (60 seconds unless given, 0 to 900) and answers with
the file when it is written within it, or with the job, job://connector/export/<id>, whose resource carries the same
answer once the file is there. The server offers resources.subscribe, so a client that can wait — the platform's
worker through Snail.Sdk.Mcp.JobClient — is told of the end, and no model is asked to call again. The job belongs to
the task the address names, not to the session: a step that connects again still reads it, a step of another task
does not. A call given up stops the waiting, not the export; a server stopping cancels it, and no file is left.
The journal is one JSON-lines file a day, and the same line in a file of the task's own, which connector_journal
reads; both go after JOURNAL_DAYS. A query whose answer the server could not read — a value .NET has no type for, a
document too deep — is answered as such and journaled like any other; a value a SQL driver cannot carry into .NET (an
interval of months, NaN) is written as the database spells it.
Finding and running tools¶
Three tools of Snail.Sdk reach the eleven above without a call per query. find_tool names the tool for a task in
the model's words — "how many orders were paid" finds connector_count — with its parameters and the command a program
calls it by. run_tools runs several calls known in advance in one, stopping at the first that fails. run_program
runs a short JavaScript program whose calls depend on each other's answers: connector.count({ … }) calls
connector_count. Every command is the tool itself: held to the session's grant (?tool=), checked by the same rules
and written into the same journal; a program is bounded in time, memory and calls, and reaches nothing of the host.
The three add about 760 tokens to the list of tools a client reads; a platform with a finder and programs of its own
can leave them out of a session's grant.
Sources¶
A source is one KV v2 secret in the stand's Vault, under secret/connectors/<name>:
| Key | What |
|---|---|
kind |
mongodb, sqlserver or postgresql |
database |
the database read |
collections |
the collections an agent may read, comma-separated; * for every one |
description |
what a person wrote about the data, shown to the agent |
readUri |
the connection string of the user that may only read: a mongodb:// URI, or for SQL the driver's own form (Host=…;Username=…;Password=… for PostgreSQL, Server=…;User Id=…;Password=…;TrustServerCertificate=true for SQL Server); the database is taken from database |
writeUri |
the connection string of the user that may write — used only after a person approves a write |
Failures¶
A refusal is {"ok": false, "error": …, "hint": …, "type": …}, flagged isError. type is the word a program
branches on (FailureTypes); the error is prose for the model and may be reworded.
type |
when |
|---|---|
arguments |
a filter, pipeline, statement, update, file name, format or wait the tool does not take, or a tool asked of the wrong kind of source |
notAllowed |
an operator or statement that writes or runs code, a collection or table the source keeps out |
noRoot, outside, malformed, notATask |
the session names no task's copy (the SDK's reasons); outside also for an exports folder that leads out of the copy |
notGranted |
a tool the session's address did not name |
noSources, noSuchSource, sourceIncomplete |
nothing declared on the stand, no source of that name, a source declared without its kind, database or readUri |
notConfigured |
no Vault address, or no APPROVAL_KEY for writes |
vaultError, databaseError, timeout, unreadable |
Vault or the database refused or failed, the query ran past its time, its answer could not be read |
journalDown |
the journal could not be written, so the answer or the step is withheld |
readOnly, tooLarge |
a source with no writing user, a write past the documents or rows one proposal may touch |
noSuchProposal, notYours, pending, rejected, applying, applied, expired, changed |
a proposal that does not exist, is another task's, nobody decided yet, a person refused, is running or ran, is past its days, or whose data changed since |
Settings¶
The settings file connector, then the SNAIL_MCP_CONNECTOR_ variables, which win: VAULT_ADDRESS, VAULT_TOKEN (read
and list under the path and nothing else), VAULT_MOUNT (secret), VAULT_PATH (connectors), WORKSPACES_ROOT
(/workspaces, where exports land), URL or PORT (http://127.0.0.1:8830/; inside the image its port on every
interface, the port the container publishes being the boundary, and on loopback alone elsewhere: LISTENS_ON_EVERY_INTERFACE,
a 0.0.0.0 URL or one beyond loopback outside a container are refused at start, naming the variable),
ROWS (50), MOST_ROWS (200), MOST_BYTES (65536), MOST_EXPORT_ROWS (100000), MOST_EXPORT_COLUMNS (1000),
EXPORT_SECONDS (600), SAMPLE (200), QUERY_SECONDS (30), JOURNAL_DAYS (365: the journal, and the proposals with
their samples of rows), APPROVAL_KEY (empty: writes off), MOST_WRITTEN (1000), PROPOSAL_SAMPLE (3),
PROPOSAL_DAYS (7).
The server is the standard's container host: a session for every client, a request a browser makes refused (at the
MCP endpoint and at the dashboard's door, /proposals), the heap trimmed when idle. The address a session opens names its task (?root=) and the tools it may use (?tool=): a tool it
does not name is left out of the list, and a call to it is refused in the envelope, type notGranted. Nothing
else checks who calls, so the server belongs on the stand's own network, reached by the platform's workers alone.
docker build -t s3l-connector-mcp:local .