setoku / site

# Setoku

> Setoku is an open-source, self-hosted MCP (Model Context Protocol) knowledge server. It gives any AI agent a read-only, audited view of the data you own (a company’s, a household’s, or your own), plus the curated context needed to use it correctly: the metric definitions, the gotchas, the reasons a naive query is wrong.

Setoku is single-tenant on purpose. There is no hosted Setoku service and no multi-tenant API: you run it on a box you own (one small VPS), and your data and your context stay there. That is the point of the product, not a gap in it. So the API described below is the API that *your* deployment exposes, not one hosted at setoku.com.

The primary interface is MCP over Streamable HTTP at `/mcp` on your box. Any MCP client can use it: Claude, Claude Code, Codex, or your own. Authentication is a per-person bearer token, revocable from the box’s web console. No AI model runs on the server, so there is no inference cost and no AI API key.

Two identities share one server and never overlap. An **analyst** token may query the data lake but holds no tool that commits knowledge. A **curator** token may commit knowledge but cannot read the lake. Accepting proposed knowledge is a human click on the admin page, outside the agent loop, so a prompt-injected session cannot rewrite what Setoku knows.

## When to use Setoku

Reach for Setoku when the answer lives in data its operator connected (a company’s, a household’s, or one person’s) and depends on their own definitions, not public knowledge.

Who it’s for:

- Companies: give agents team-by-team access to revenue, logs, and deploys, for debugging and analysis. Definitions like “active customer” get written down once.
- Families: shared accounts and calendars, so the partner who doesn’t write SQL gets the same answers.
- Just you: your own accounts and repos, queryable from your phone and the web as well as your desktop.

Use it when:

- The question is about the operator’s own revenue, deploys, spending, mail, or repos. The data lives in their database, Slack, GitHub, email, or bank.
- The data keeps changing (a bank, an inbox, an issue tracker), so an export is stale on arrival.
- You need the operator’s definition of a term first: what counts as an active customer, which account is the joint one, which charges were reimbursed.
- A naive query would be wrong in a way only an insider knows: soft-deleted rows, a test tenant, a transfer between your own accounts counted as income. You want that caveat before you run SQL.
- You want a dashboard on a link someone else can open, on live data, not a screenshot.
- An agent will read untrusted text (mail, logs, chat) in the same session. That session can’t rewrite what Setoku knows, so an injected instruction can’t become a remembered fact.
- You want the answer to be auditable later: every query and knowledge change is logged on your box.

Do not use it when:

- The question is general knowledge or public data. Setoku only knows the data its operator connected.
- The data is a static file on your disk. Query it locally. Setoku is for data that lives in other services and keeps changing.
- You need to write to the operator’s database. Every data path is read-only, enforced by database role. There is no write tool and no escape hatch.
- You want a hosted API to sign up for. There is none. Setoku is self-hosted, and the endpoint you call is the operator’s own box.
- You want a model to run server-side. Setoku runs no inference.

How an agent should call it:

1. Connect to the box’s MCP endpoint (Streamable HTTP) at `https://<their-box>/mcp` with the person’s bearer token, or paste `https://<their-box>/mcp/<token>` into a connector dialog that has no header field.
2. Call find_context FIRST, every time. It returns the curated notes for the question, including which tables to trust and which to avoid.
3. Then get_schema, then run_query.
4. If the context is wrong, call report_correction. It lands as a proposal for a human to accept. An agent session can’t commit knowledge by itself.

The same guidance, machine-readable, is in [/.well-known/mcp.json](https://setoku.com/.well-known/mcp.json), [/.well-known/agent-card.json](https://setoku.com/.well-known/agent-card.json), and [/.well-known/agent-skills/index.json](https://setoku.com/.well-known/agent-skills/index.json).

## Setoku developer resources

- [Setoku API reference](https://setoku.com/docs): the HTTP API, authentication, the MCP tool surface, quickstart, and the security model. Markdown twin: [/docs.md](https://setoku.com/docs.md).
- [Setoku homepage in markdown](https://setoku.com/index.md): the whole product page as one canonical markdown document, no HTML to parse. Both content pages — this one and /docs — also answer `?mode=agent` with their markdown twin; the JSON documents below answer as themselves.
- [Setoku MCP manifest](https://setoku.com/.well-known/mcp.json): where the MCP server is, which transport it speaks, and how to authenticate.
- [Setoku agent card](https://setoku.com/.well-known/agent-card.json): what Setoku is for, its skills, and the endpoint to call.
- [Setoku agent skills index](https://setoku.com/.well-known/agent-skills/index.json): the shipped skills, each with a name and a description.
- [Setoku OpenAPI specification](https://setoku.com/openapi.json): OpenAPI 3.1 for the Setoku gateway HTTP API, covering the MCP endpoint, health, published apps, and the installer. Mirrored at [/api/openapi.json](https://setoku.com/api/openapi.json).
- [Setoku catalog API](https://setoku.com/api/index.json): machine-readable product metadata — version, install commands, every document this site publishes, and how to reach the MCP endpoint.
- [Setoku MCP tool catalog](https://setoku.com/api/tools.json): every MCP tool, with the role each one requires.
- [Setoku connector catalog](https://setoku.com/api/connectors.json): the data sources Setoku ingests.
- [Setoku source repository](https://github.com/Hedgy-Labs/setoku): Apache-2.0, the full server, skills, and deploy scripts.

## Try Setoku without installing it

- [Setoku public demo](https://setoku.com/#demo): a live box wired to a synthetic pro-sports-club dataset (ticketing, sponsorship, concessions, payroll, broadcast rights). Add `https://demo.setoku.com/mcp/85315b4240ff6ded111072f950ac6f14167d920fdb765144` as a custom MCP connector. The token is public on purpose and read-only.
- [Setoku demo app: Sponsorship pricing table](https://demo.setoku.com/p/7e38381ced6517329947b14d): inventory and rates for sponsorship placements, built and published by an agent on live demo data.
- [Setoku demo app: Bulldogs attendance forecast](https://demo.setoku.com/p/a7a1240ae0bc202c5eefa1cc): projected gate for upcoming home games, built and published by an agent on live demo data.
- [Setoku demo box health](https://demo.setoku.com/healthz): a real, credential-free REST endpoint you can call right now to see the shape of the API.

## Install Setoku

- [Setoku quickstart](https://setoku.com/#quickstart): add the Claude Code plugin (`/plugin marketplace add Hedgy-Labs/setoku`), then run `/setoku:onboard` from your project directory.
- [Setoku manual server setup](https://setoku.com/docs#install): clone the repo onto a fresh Ubuntu VPS and run `deploy/bootstrap.sh`.

## Setoku skills

- `/setoku:compact-knowledge`: Periodically tidy the Setoku knowledge store in a curator session — merge duplicate facts, resolve contradictions, tighten verbose docs, and flag stale knowledge. Use when the user asks to compact / clean up / dedupe / tidy knowledge, or when /admin/knowledge shows merge / contradiction / verbose flags.
- `/setoku:connect`: Connect a data source to Setoku end-to-end — ensure a box exists, wire the source up (read-only), verify the agent actually understands the data, and write what it learns back as knowledge. Use when the user says "connect \<source>", "hook up \<source>", "add a data source", "set up Setoku", or "/setoku:connect".
- `/setoku:curate`: Review pending Setoku knowledge candidates and promote, edit, or reject them — conversationally, no git or dev skills required. Use when the user asks to curate/review setoku knowledge, or when list_entities reports pending corrections.
- `/setoku:eval`: Run the Setoku golden-question eval for this repository and report a scorecard. Use when the user asks to eval/test setoku answer quality, or after significant context-artifact changes.
- `/setoku:generate`: Generate or refresh Setoku’s business-context knowledge by reading this repository’s code — ORM schemas, business logic, migrations, existing docs — and saving it to the knowledge store (commits directly on a curator connector, or proposes for human approval on the everyday analyst connector — no SSH needed). Use when the user asks to generate/update/refresh business context, when setoku tools report an empty knowledge store, or when schema drift is detected.
- `/setoku:onboard`: First-run setup for Setoku in a repo — connect the business database, generate context from the code, and answer a first question end-to-end. Use when the user says "set up setoku" or "onboard", or when setoku tools report missing config. (Thin wrapper over /setoku:connect.)

## Optional

- [Setoku architecture](https://setoku.com/#architecture): how the gateway, the ClickHouse lake, and the knowledge store fit together on one box.
- [Setoku security model](https://setoku.com/#security): what the token is, why reads are governed by database roles rather than by parsing SQL, and why writes pass through a person.
- [Setoku issue tracker](https://github.com/Hedgy-Labs/setoku/issues): bugs and feature requests.
- Contact: hello@setoku.com