Connecting

Two ways in, both speaking the same xyTalk: the TCP wire (CLI and drivers) and the MCP endpoint for agents.

CLI / REPL (TCP)

$ cargo run -p xyzdb-cli -- --host 127.0.0.1 --port 2505
xyzdb> FIND "clients" WHERE code = "ACME"

Python driver

Official client — pip install xyzdb. A thin wrapper over the TCP wire with a builder for the pipeline.

from xyzdb import connect

with connect("localhost", 2505) as db:
    db.put("creditos", {"*rfc": "ACME-001", "monto": 50000})
    rows = db.find("creditos", {"rfc": "ACME-001"}).pull(depth=2).execute()

The wire protocol

The server speaks a versioned, length-framed TCP protocol on --port (default 2505): a version byte, an optional auth frame carrying the bearer token, then requests in binary or JSON. Plain HTTP on the same port is auto-detected (/ · /stats). Responses cap at 256 MB; wrap it in TLS 1.3 via --tls-cert / --tls-key.

MCP (agents)

The MCP server speaks JSON-RPC 2.0 over stdio to the agent host, and reaches the engine in-process (--embed) or over TCP (--connect). --query-policy restricts what the query tool may run; --query-timeout-ms (default 30000) bounds it.

{
  "mcpServers": {
    "xyzdb": {
      "command": "/path/to/xyzdb-mcp",
      "args": ["--embed", "/path/to/data", "--query-policy", "no-destructive"]
    }
  }
}

Tools, resources & policy

stats · engine internals as JSON (same shape as /stats).
query · run any xyTalk (subject to the policy and timeout).
list_lobes · lobes and their counts as structured JSON.
describe_lobe · a lobe's anchors, ghosts and fields.

Three read-only resources mirror the tools: xyzdb://lobes, xyzdb://stats, xyzdb://lobes/{name}.

Policy by parsed AST · full = all · no-destructive = blocks deletes/drops · read-only = reads only.