Setoku: Self-hosted AI knowledge server for company data

Setoku is an open-source, self-hosted MCP server (Apache-2.0 license, available on GitHub) designed to make AI agents fluent in company data while maintaining security and accuracy. The product ships as a Claude Code plugin and runs on a single inexpensive VPS, with no model inference on the server itself, so teams pay only for hosting, not for added AI compute.

The core architecture consists of three layers. First, a ClickHouse data lake ingests logs, events, and read-only mirrors of production databases, allowing the AI to run arbitrary queries (scans, GROUP BYs, aggregations) quickly on a columnar engine. Second, a knowledge store records metric definitions, entity documentation, and the "gotchas" that make naive queries wrong—for instance, deduping fans by normalized email and excluding internal accounts when counting unique users. Third, a Setoku gateway exposes three kinds of MCP tools: context tools (find_context, get_metric, report_correction) that let the AI consult what the data means before querying; read-only query tools (get_schema, run_query) that enforce SELECT-only access at the database engine level; and app tools (publish_app, update_app) that turn answers into shareable dashboards on live data.

The demo illustrates the workflow using fictional data for the Bonita Bulldogs, a pro sports club with ticketing, sponsorship, concessions, payroll, and broadcast-rights data. When asked "How many unique fans do we have?" the AI answers 71,204—deduped by normalized email, internal accounts excluded, not the raw 92,118. When asked for total annual revenue and media rights, it returns $192M total with ~$90M from media rights (the largest line), having reconciled five systems to the same units. For ticket revenue this season, it returns $46.8M with cents reconciled to dollars and refunds, exchanges, and comps excluded. Crucially, when asked for total merchandise revenue, the system flags that most merch is sold via Fanatics (not in this data) and refuses to return a wrong total. The AI can also build dashboards—two live examples on the demo data include a sponsorship pricing table (inventory and rates for placements) and a fan lifetime value segment (fans by spend across tickets, merch, and concessions).

Setoku is installed as a Claude Code plugin (/plugin marketplace add Hedgy-Labs/setoku, /plugin install setoku@setoku) and onboarded with /setoku:onboard from the customer's project directory. Onboarding stands up the server, authenticates Claude, wires the production database as read-only, and generates initial knowledge from the codebase. Additional Claude Code skills—/setoku:connect (add data sources), /setoku:generate (write business context from code), /setoku:curate (review and approve pending knowledge)—support configuration and maintenance. For manual setup, teams clone the GitHub repo on a fresh Ubuntu VPS, run ./deploy/bootstrap.sh (which installs Docker, generates secrets, obtains an HTTPS certificate), and then add the plugin and run /setoku:onboard to connect the box to their Claude instance.

Security is enforced at multiple levels. MCP connector URLs act as credentials (like database connection strings), with tokens embedded in the URL; each person gets their own revocable link. App links are login-gated by default and made public only by admin action. Read-only access is enforced by the database engine (SELECT-only role), not by SQL parsing, with row caps, statement timeouts, and an append-only audit log on every query. Critically, agents can only propose changes to the knowledge store; a person must accept them on the admin page outside the agent loop, so a prompt-injected session cannot rewrite the system's understanding. All data stays on the customer's infrastructure; only the proxy faces the internet, and Postgres and ClickHouse are never exposed. Apps store their own state (todos, votes, annotations) in a sandbox belonging to the app, not the customer's database, so a misbehaving app at worst corrupts its own notes.

Setoku addresses a common problem in enterprise AI: giving language models access to internal data without exposing databases, adding inference cost, or trusting the AI with write access. The system separates concerns cleanly—a ClickHouse data lake mirrors read-only sources, a knowledge store captures metric definitions and data gotchas that the AI consults before querying, and a gateway enforces access controls at the database level rather than trusting SQL parsing. The demo's fictional sports club shows this in action: the AI correctly identifies that 71,204 fans are unique (deduped by email, excluding internal accounts), reconciles revenue across five systems to $192M with media rights as the largest line at ~$90M, and flags missing merchandise data (most sold via Fanatics, not in the system). This last behavior—acknowledging gaps rather than returning wrong totals—is critical for business trust.

The architecture keeps all data on the customer's own infrastructure; only the proxy is public, and production databases are never exposed. Knowledge changes pass through human approval, preventing prompt injection from corrupting the system's understanding. Apps and dashboards run on live data through the same governed read-only path, with each app's internal state (notes, votes) isolated in a sandbox so a misbehaving app cannot corrupt the underlying database. The low hosting cost ($5–12/mo) and integration with existing AI tools (via MCP) make it accessible to teams that do not want to build custom knowledge pipelines or pay for separate inference infrastructure.

No comments yet. Be the first to share your thoughts!