MCP
Your server speaks MCP at /mcp: http://127.0.0.1:3699/mcp for a local zsql serve. Point any MCP client at it and the agent gets the same reads the API has, as tools: list the branches, search the catalogue, plan SQL from a spec. Nothing to deploy or switch on. It is the same server, and it still never runs a query.
Connect
claude mcp add --transport http 0sql http://127.0.0.1:3699/mcpFor a model with security policies, add the context the agent plans as:
claude mcp add --transport http 0sql http://127.0.0.1:3699/mcp \
--header 'Zsql-Context: {"email":"me@example.com"}'Set ENABLE_TOOL_SEARCH=false in the environment Claude Code runs in. It then loads the 0sql tool schemas up front instead of behind a search, which in our evaluation cut a question from 4.8 model round trips to 3.4 and raised the pass rate. It applies to every MCP server in the session.
claude.ai reaches a server over the internet, and the 0sql server must not be on it. So a hosted client connects to the service you put in front: your own endpoint, with whatever sign-in it has, that forwards POST /mcp to the server on your private network and adds the Zsql-Context header for the signed-in user. In claude.ai: Customize, Connectors, Add custom connector, and give it that service’s URL.
Streamable HTTP, stateless, JSON only. Each POST carries one JSON-RPC message. There are no sessions and no event stream: GET and DELETE answer 405, and the OAuth discovery paths under /.well-known are plain 404s. Protocol revisions 2025-11-25, 2025-06-18 and 2025-03-26 are answered; a client asking for another gets the newest.
Who a call is planned for
A row-level policy reads the security context a query is planned for. Over the API your application sends it in the request body. Over MCP a model writes the arguments, and a model must not choose who it acts as, so the context is never an argument:
- The
Zsql-Contextheader carries it, as the same JSON object the API takes incontext. It applies to the one tool call the request carries. The model never sees or writes it. - A
contextamong a tool’s arguments is refused, never dropped:a security context is not accepted here: who a query is planned for is fixed by the connection. - No header is no context. A branch with policies then refuses with
ContextRequired, as the API does. - A header that is not a security context is a 400: not JSON, not an object, or with a member the context does not have.
curl -s http://127.0.0.1:3699/mcp \
-H "Content-Type: application/json" \
-H 'Zsql-Context: {"email": "agent@example.com", "groups": [{"name": "CC-TMNT", "tags": ["call_center_id:TMNT"]}]}' \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": {"name": "sql", "arguments": {"uid": "customer-service", "spec": {"projections": [{"field": "aht mins"}]}}}}'
The header is as trusted as the request body is over the API: whoever can reach the server can claim any context, system_admin included. The service in front is what stands between a user and that claim, so it must set the header itself from its own session and never pass one through from its caller. It also decides which projects a user may name: the server lists and plans every deployed branch for anyone.
Tools
Every tool but list_projects takes a project uid and a branch; the branch defaults to the project’s production branch. sql, explain and explore take a query spec, never an expression line, and the spec’s JSON schema travels in the tool definition. No tool deploys, changes or runs anything.
| Tool | Returns |
|---|---|
list_projects | every deployed branch, with the size of each model |
fields | with no q, the whole catalogue of a branch as one text; with q, the fields containing or near the phrase, best first |
tables | the tables of a branch: physical name, datasource, cost, fields |
values | one dimension’s sampled values, when the project deployed any. Takes a dimension, by uid or name |
explore | given a spec, the dimensions and measures that can still be added |
sql | the SQL for a spec, with the datasource and adapter it is for |
explain | the same, with timings, phases and the node graph |
values is how a model stops guessing at a filter’s spelling. Sampling is off until a project turns it on, so the tool’s own description tells the model what to do when there are none: a branch whose summary in list_projects shows values 0 has no samples, the call answers NotFound, and filter values then have to come from the question or the field’s description.
A result carries a text block with the JSON and structuredContent with the same value. A refusal from the planner comes back as the tool’s own result with isError, carrying the API’s class and message, so the model reads why (an unknown field, with the nearest ones) rather than a transport failure.
initialize returns the server’s instructions and a catalogue of every deployed branch, under 48 KB. A client that keeps them in its prompt can answer a question with one sql call. Claude Code keeps about 2,000 characters of a server’s instructions, so there the model fetches the catalogue with fields first.
Limits
One HTTP request is one tool call. It is admitted as planning work, and fields and explore take an explore seat as well; when the server is full the answer is 503 with Retry-After, as on the API, so a client’s usual back-off applies. There are no rate limits: pacing callers is the job of the service in front. 30 seconds per call, one megabyte per body. Specs are planned in memory and never stored; an initialize writes one log line naming the client it declared.
Try it
Serve the demo’s customer-service model (or any project of yours), connect it, and ask: which call centers have the longest average handle time? The agent calls sql with a spec, and you get the statement to run. The chat dashboard tutorial builds the same loop into an application with the API.