NAME

setoku-developers — build against Setoku, the self-hosted MCP knowledge server

SYNOPSIS

Setoku is an open-source MCP server you run on your own box. It gives an AI agent a read-only, audited path into your data plus the curated context to use it correctly. This page is the developer reference: the API, the tools, the auth model, and how to get a box of your own.

# the whole API surface, from a real running box
curl https://demo.setoku.com/healthz
curl https://setoku.com/openapi.json

# product metadata, for agents that would rather fetch than scrape
curl https://setoku.com/api/index.json
curl https://setoku.com/api/tools.json

RESOURCES

Setoku OpenAPI specificationOpenAPI 3.1: The gateway HTTP API: the MCP endpoint, health, published apps, and the installer. /openapi.json, mirrored at /api/openapi.json.
Setoku catalog APIJSON: Version, install commands, links, and how to reach the MCP endpoint: /api/index.json. The tool surface is at /api/tools.json and the source list at /api/connectors.json. All three are generated from the source tree, so they track the release.
Setoku llms.txttext: The same map in prose, for agents reading rather than parsing: /llms.txt.
Setoku sourceApache-2.0: The full server, the setup skills, and the deploy scripts: github.com/Hedgy-Labs/setoku ↗

API

The API is your box, not ours. Setoku is single-tenant on purpose: there is no hosted Setoku service and no multi-tenant API at setoku.com. You run the server, and your data and your context stay on hardware you control. So every endpoint below is one your deployment serves. The public demo box, demo.setoku.com, is a real one you can call right now.

The primary interface is MCP over Streamable HTTP. The REST endpoints are the credential-free surface around it: box health, and apps an agent published.

POST /mcpbearer token: The Model Context Protocol endpoint. Point any MCP client at it. The server is stateless per request: identity binds from the token, and which tools get registered depends on that identity’s role. Clients whose connector dialog takes only a URL can use /mcp/<token> instead.
GET /healthzpublic: Knowledge-store size, disk usage, dependency pings, and mirror freshness. 503 when a dependency is down or the data disk is 90% full. Cached about 5 seconds, so polling it amplifies nothing.
GET /p/<id>public apps: An app an agent built and published. Credential-free only for apps an admin has explicitly made public. /p/<id>/data returns freshness metadata and never re-runs a query; /p/<id>/state is the app’s own sandboxed key/value store, which can never reach a business source.
GET /i/<token>installer: A shell script that configures an MCP client for this box, personalized to the token. For curl -fsSL … | sh.

Full request and response schemas: /openapi.json.

TOOLS

Setoku’s MCP tools carry one rule: look up what the data means before you touch it. The authoritative list, with the role each tool needs, is generated from the source at /api/tools.json — the groups below are a reading guide to it, not a second source of truth.

Contextfind_context · list_entities · describe_entity · get_metric: Read what the data means first: canonical metric definitions, entity docs, and the gotchas that make a naive query wrong. find_context is documented as “always call FIRST.”
Proposereport_correction · list_corrections: An agent can propose a change to what Setoku knows. It lands as pending. A person accepts it on the admin page, outside the agent loop.
Datalist_sources · get_schema · run_query: Read-only SQL against the box’s ClickHouse lake and the biz.* mirror of your database. Row caps, statement timeouts, an append-only audit log.
Appsapp_guide · publish_app · update_app · list_apps · get_app · unpublish_app: Turn an answer into a small web app on live data, published at a link the team can open.
Curateupsert_context · resolve_correction: Commit curated knowledge. Registered only on a curator token, which cannot read the lake. See MEMBRANE.
Janitordraft_correction · reject_correction: Registered only on a janitor token, used by the automated curation pass. It can attach a draft edit to a pending correction, or auto-reject one, and nothing else — both grant zero authority, so the drafting agent reads untrusted pending content while holding no tool that commits anything.

AUTHENTICATION

Setoku authenticates with a per-person bearer token. Send it as Authorization: Bearer <token>, or as a path segment (/mcp/<token>) for MCP connector dialogs that accept only a URL and have nowhere to put a header.

Each person gets their own, minted from the box’s web console and revocable there, so you revoke one person instead of rotating the team’s. Treat the whole URL as a credential, like a database connection string.

On OAuth 2.0. Setoku does not implement OAuth 2.0 or OpenID Connect today, and does not publish authorization-server metadata, because there is no authorization server behind it. This is a deliberate, documented decision rather than an oversight: for a small self-hosted deployment, one credential model is less to get wrong than two, and the blast radius of the current token is bounded (read-only, propose-only, one-click rotation). When OAuth does land it will replace the bearer path rather than sit beside it. The full engineering scope, including the resource-server and authorization-server pieces the MCP spec requires, is written up in docs/oauth-scoping.md ↗. If OAuth is a requirement for you, say so on the issue tracker: that is the signal that moves it.

MEMBRANE

The load-bearing security design, and the thing most worth understanding before you build against Setoku: two identities, one server, never on the same session.

Analystreads the lake · proposes only: May query your data, including untrusted bulk text like logs and Slack. Holds no tool that commits curated knowledge. The most it can do is report_correction, which lands as pending.
Curatorcommits knowledge · no lake read: May commit curated knowledge, and cannot read the lake. So a session that could be prompt-injected never holds the write tool, and the session holding the write tool never reads the text that would inject it.

Accepting pending knowledge into curated context is a human click on the admin approval surface, outside the agent loop. No MCP tool creates users, grants access, or commits knowledge on its own. Read-only and per-source access are enforced by the database engine through per-role grants, never by parsing SQL.

INSTALL

Setoku installs as a Claude Code plugin. Add it, then run onboarding from the codebase you want Setoku to learn from:

# 1 · add the plugin (skills only)
/plugin marketplace add Hedgy-Labs/setoku
/plugin install setoku@setoku

# 2 · from your project directory
/setoku:onboard

Onboarding stands up the server, auths your client, wires your database read-only, and generates the first knowledge from your code. You stay in the loop for anything that touches your data.

Or stand the server up by hand, on a fresh Ubuntu VPS:

git clone https://github.com/Hedgy-Labs/setoku /opt/setoku
cd /opt/setoku
SETOKU_ADMIN_USER=you ./deploy/bootstrap.sh

That installs Docker, generates secrets, gets an HTTPS certificate, and prints the connect command. A ~$5/mo VPS is fine for a personal box; something like OVH’s VPS-2 is plenty for a team. No AI model runs on the server, so there is no inference cost and no AI API key.

CONNECT AN AGENT

Any MCP client works. In Claude, open Settings → Connectors → Add custom connector and paste your box’s MCP URL. To try the API before you have a box, use the public demo, which is read-only and whose token is public on purpose:

https://demo.setoku.com/mcp/85315b4240ff6ded111072f950ac6f14167d920fdb765144

It is wired to a synthetic dataset for a fictional pro sports club: ticketing, sponsorship, concessions, payroll, broadcast rights. See the demo walkthrough for questions worth asking it.

CONNECTORS

Every source lands in a local ClickHouse lake. Your app database connects read-only and is mirrored in on a cron; the rest is ingested as it happens. Current list, generated from the source tree: /api/connectors.json.

No connector for your source yet? The included setup skills give a coding agent the patterns to wire one up itself, and /setoku:connect walks it end to end. If you build a good one, send a pull request.