Your agent's one tool.
Every kind of data behind it.
Agent frameworks wire a database, a vector store, a search index and a retrieval layer together, then spend their time debugging the seams. Data Oil is one surface an agent calls - with a credential, a budget and an audit line that are the agent's own. Any agent that can make an HTTP call can use it today; one that speaks MCP adds a single line.
What an agent needs
Eleven things an agent needs from a data store, all shipped
Plain HTTP and JSON, or MCP
/api/v2 with typed parameters and nothing to install - or @dataoil/mcp, added to Claude Desktop or Cursor with one line of configuration. A complete client is under sixty lines.
Failure it can branch on
A stable errorCode, the arithmetic of the refusal beside it, and a retryable header - so the agent decides what to do before it parses anything.
Streaming, so it can act early
Rows arrive one at a time and the agent acts on the first before the last is produced. Paging under writes never skips or repeats a row.
Answers with evidence, not just text
The answer, its sources, its citations and a confidence score. An agent can cite it, check it, or decline to act on a low score.
To see what it would send
One call hands back the exact prompt, evidence and byte count that would go to your model - without sending it.
The schema in words
The descriptions you wrote on collections and columns, so an agent plans against what the data means rather than guessing from a column name.
Its own credential
A key scoped to named databases and one permission, with an expiry, refreshed without downtime and revoked in one call. A key may not mint a key.
A wake-up when data changes
A change feed it resumes from, so a downstream agent never misses a committed change and never sees one that was rolled back.
A no with a number
A quota refuses before a statement is even parsed, and says what was used, what is allowed and when it resets.
Accountability
Every statement and every question lands in your audit under the job identifier the agent chose - and nothing can remove a line.
One store to reason over
Rows, vectors, keywords, relationships, transcripts, frames and eighteen languages, behind one call. The agent calls one tool, once.
An agent's first four calls
A key, a question, an answer it can cite, a refusal it can read
1. Mint the agent its own key
POST /api/v2/tokens
{ "name": "the triage agent", "databases": ["tickets"],
"permission": "read-only", "lifetimeSeconds": 2592000 }Scoped to one database and read-only, expiring in thirty days. The secret appears once; GET /api/v2/tokens lists the key without it.
2. Ask, with a job identifier
POST /query
X-Job-ID: triage-4471
X-Database: tickets
{ "query": "which open tickets mention the same outage as ticket 4471",
"collection": "tickets", "max_results": 10 }The identifier is the agent's; every line it produces in the audit and on the bill carries it.
3. Read the evidence before acting
{ "answer": "Four open tickets describe the same outage ...", "confidence": 0.87,
"sources": [ { "id": "#31:9", "title": "tickets / 4470" }, ... ],
"evidence": [ { "source_id": "#31:9", "citation_key": "[1]", "relevance_score": 0.93 }, ... ] }Sources it can open, evidence with citation keys, and a confidence score it can set a threshold on.
4. Be refused with the arithmetic
429"errorCode": "RequestQuotaExceeded" "arguments": { "used":60, "allowed":60, "resetsAt": "2026-09-14T09:15:00Z" } X-Retryable: true
A quota refusal says what was used, what is allowed and when it resets, and the header says whether to retry. No parsing, no guessing.
The same calls, in C#, Python and JavaScript, are in the see the manuals for further details; every example there is parsed by the engine's own build before it is published.
Governance for agents
The four questions your security team will ask about the agent, answered before they ask
What can it reach?
Only the databases its key names, the verbs its permission grants, and the columns its role allows. A column it may not read is simply not there.
What does it send to the model?
Exactly what one call will show you first: the prompt, the evidence, the byte count. The model is yours and the key is yours.
How do we stop it?
Revoke the key, and it stops. Or narrow it, and a quota refuses it before a statement is parsed.
What did it do last Tuesday?
Every statement and every question, in your own audit, exportable to a spreadsheet. Your agent's history is your record, not the agent's.
Where agents already fit
Three shapes an agent takes on Data Oil
The retrieval agent
Answers questions over documents, tickets, recordings or tables, with citations. The whole retrieval stack sits behind one call.
The pipeline agent
Acts on each committed change - enriches, classifies, routes, notifies - and picks up exactly where it left off after any interruption.
The operator agent
Runs reports, reconciliations and clean-ups on a scoped key, and leaves an audit trail a person can read.
One line in Claude Desktop
The MCP server
{ "mcpServers": { "dataoil": { "command": "dataoil-mcp",
"env": { "DATAOIL_URL": "https://acme.dataoil.tech", "DATAOIL_DATABASE": "tickets", "DATAOIL_TOKEN": "dot_..." } } } }
Four tools over one database, each bounded by what the key already gets: its rights, its quota, a refusal it can read, and its line in your audit.
DataOil.Client · NuGet
dotnet add package DataOil.Client. .NET 8 and 10, no dependencies beyond the framework. Streams the NDJSON, follows the cursor, types every refusal, retries a lost race.
dataoil · PyPI
pip install dataoil. Standard library only. The same client, plus retrievers for LangChain and LlamaIndex with dataoil[langchain] and dataoil[llamaindex].
@dataoil/client · npm
npm install @dataoil/client. JavaScript and TypeScript on fetch, no dependencies; query() is an async iterator over the streamed body.
@dataoil/mcp · npm
npm install -g @dataoil/mcp. A Model Context Protocol server over one database - query, schema, ask, ingest - for Claude Desktop, Cursor and any MCP client, on the key's own rights, budget and audit.
+What the platform does not pretend to beOpen
Data Oil ships no agent framework and no model. It is the data surface an agent calls, over HTTP or MCP, from whatever framework you run, against whatever model you nominated. That is deliberate: the framework changes every quarter and the model every month, and the store an agent reasons over should outlive both.
Bring your agent
A paid proof of concept with your agent at the keyboard
Four weeks, one workload your agent has to do, your data, your model endpoint, its own key from day one. You leave with the agent running against a tenancy you signed into, the twenty questions it has to answer answered with citations, the audit of everything it did, and an invoice that is the forecast for production.
Questions this page raises
Three for your next agent review
What can your agent reach that you did not grant?
A key scoped to a database and a verb, revoked in one call.
Read the answer →Can you show what your agent sent to the model last Tuesday?
Byte for byte, and the audit line that says which agent asked.
Read the answer →How many stores does your agent have to keep in its head?
One, and one tool to call.
Read the answer →