Reference

SDK, CLI & MCP

Beyond raw REST, SuperChargeDB ships first-party developer surfaces: TypeScript + Python SDKs, a CLI, and an MCP server. Each is a thin, typed client of the same core — so the scope clamp, grant intersection, and ACL filter are identical everywhere.

Package names are being finalized

The install names below (@superchargedb/sdk, superchargedb, etc.) are plausible but not yet locked. Check the release notes for the exact published names; the usage shapes are stable.

TypeScript SDK#

A typed client over the REST contract. Every method mirrors an endpoint and returns the same shapes documented in the REST reference.

install

npm install @superchargedb/sdk
# or: pnpm add @superchargedb/sdk

quickstart.ts

import { SuperChargeDB } from "@superchargedb/sdk";

const db = new SuperChargeDB({
  baseUrl: "https://superchargedb.krisch1218.workers.dev",
  token: process.env.SUPERCHARGEDB_TOKEN!,   // Authorization: Bearer <token>
  scope: "acme/alpha/backend",               // default X-Aegis-Scope
});

// Multimodal hybrid search
const { hits, trace } = await db.search({
  q: "failover during the Q3 keynote",
  planes: ["text", "audio", "doc_visual"],
  top_k: 8,
  rerank: true,
});

// Grounded, cited answer
const { answer } = await db.answer({ q: "How fast was the cutover?", planes: ["text", "doc_visual"] });
console.log(answer.text, answer.nli_faithfulness);
for (const c of answer.citations) console.log(c.index, c.source_uri, c.locator);

// Ingest text units
await db.ingest({ units: [{ text: "Q4 renewals close in H1.", scope: "acme/alpha/backend" }] });

// Read + verify the audit chain
const { rows } = await db.audit.list({ limit: 50 });
const { intact, break_at } = await db.audit.verify();

Python SDK#

The same surface, idiomatic for Python — sync and async clients.

install

pip install superchargedb

quickstart.py

import os
from superchargedb import SuperChargeDB

db = SuperChargeDB(
    base_url="https://superchargedb.krisch1218.workers.dev",
    token=os.environ["SUPERCHARGEDB_TOKEN"],
    scope="acme/alpha/backend",
)

# Multimodal hybrid search
res = db.search(q="failover during the Q3 keynote", planes=["text", "audio", "doc_visual"], top_k=8)
for hit in res.hits:
    print(round(hit.score, 3), hit.unit_id, hit.locator)

# Grounded, cited answer
ans = db.answer(q="How fast was the cutover?", planes=["text", "doc_visual"]).answer
print(ans.text, ans.nli_faithfulness)

# Ingest + audit
db.ingest(units=[{"text": "Q4 renewals close in H1.", "scope": "acme/alpha/backend"}])
report = db.audit.verify()   # -> { intact: True, checked: 128, head_seq: 128, break_at: None }

CLI#

The CLI wraps the same client for scripts, CI, and quick exploration. It reads SUPERCHARGEDB_TOKEN from the environment and emits JSON for easy piping into jq.

install

npm install -g superchargedb
# then authenticate
export SUPERCHARGEDB_TOKEN=aegis_sk_alice

usage

# Multimodal search
superchargedb search "failover during the Q3 keynote" \
  --scope acme/alpha/backend --planes text,audio,doc_visual --top-k 8

# Grounded cited answer
superchargedb answer "How fast was the cutover?" --scope acme/alpha/backend

# Ingest from a file of JSON units
superchargedb ingest ./units.json --scope acme/alpha/backend

# Read + verify the audit chain
superchargedb audit list --limit 50
superchargedb audit verify        # -> { "intact": true, "checked": 128, "break_at": null }

MCP server#

The MCP server exposes SuperChargeDB as agent-native tools over the Model Context Protocol, so an LLM agent can search, answer, ingest, and audit — under the exact same enforcement, with MCP recorded as the surface in every audit row. Auth is OAuth 2.1; the agent can never widen scope beyond the granted principal.

mcp client config

{
  "mcpServers": {
    "superchargedb": {
      "command": "npx",
      "args": ["-y", "@superchargedb/mcp"],
      "env": {
        "SUPERCHARGEDB_URL": "https://superchargedb.krisch1218.workers.dev",
        "SUPERCHARGEDB_TOKEN": "aegis_sk_alice"
      }
    }
  }
}

Exposed tools

Tool	Maps to	Purpose
`search`	`POST /v1/search`	Multimodal hybrid retrieval with Locators.
`answer`	`POST /v1/answer`	Grounded, cited synthesis with a faithfulness score.
`ingest`	`POST /v1/ingest`	Add units (write permission required).
`audit`	`GET /v1/audit` · `/verify`	Read and verify the tamper-evident log.

One core, many surfaces

UI, CLI, REST, SDK, and MCP are all clients of the same enforced core — there is no privileged path to your data. See the security model and architecture.