The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Kirk — Unsupervised Structural Change Detection listing page.
Ulysses is an algorithmic primitive for computing the complete pairwise structure of a system — every variable against every other, all at once — unsupervised, real-time, on a CPU.
Kirk is the first algorithm on Ulysses. It signals the moment structure breaks.
Borg is the second algorithm on Ulysses. Radio-frequency spectrum anomaly detection.
This repository is the public documentation and configuration surface for the hosted kirk-mcp MCP server at kirk-mcp.kavara.ai — where Kirk is exposed as a set of MCP tools for validation and discovery use cases.
The Kalman filter for the non-Gaussian, non-stationary world.
The Kalman filter is a special case: linear, Gaussian. Ulysses closes the full-joint intractability that stopped the Boltzmann-machine family, in polynomial time, and Kirk applies that primitive to non-stationary streams. Not a foundation model — the Kalman filter's category, not GPT's. The IP is the math.
Fastest path: paste this into your assistant and it will configure your client for you — Grok, Claude, Cursor, Copilot Chat, or any other MCP client.
To configure by hand instead, read on.
You need a credential. Kavara issues one of two kinds — use whichever you were given:
| You were given | Use this |
|---|---|
A URL like https://kirk-mcp.kavara.ai/mcp/k_... | Personal key. Works as a URL or as a header. |
| A client ID and secret pair | Service token. Header only. |
Most clients are configured with a personal key. It is the same key either way — as a header it stays out of shell history, process listings and request logs, so prefer the header form wherever your client supports headers.
Personal key, as a header (recommended):
Personal key, as a URL — for clients that accept only a URL (the Claude Desktop and claude.ai connector dialogs, for example):
Service token, if that is what you hold:
Command-line clients that take flags rather than JSON, such as Claude Code:
First 100 inference units are free per new account. Contact sales@kavara.ai
to be issued a credential.
Ask your client to call kirk_verify_engine. It costs nothing and returns
status: ok plus the engine sha. Record that sha alongside any result you keep —
results from different engine builds are not interchangeable.
If a call fails, see troubleshooting before changing your credential; the most common failure is not a credential problem.
For per-client templates see examples/: Claude Desktop, Claude Code,
Cursor, VS Code, Grok, a generic streamable-HTTP client, and a Python client.
User-Agent. Cloudflare rejects some default client agents on this zone with a
1010 "browser signature banned" error that arrives as a 403. Set an explicit
User-Agent before you start debugging credentials.URL key ... is unknown. The key was mistyped, or it has been revoked.
Keys are per person and are not shared; ask for a new one.kirk_billing_show.kirk_list_models that errors when called. The catalogue
lists registered models; it is not a liveness check. Please report it.Almost all of AI is supervised: predict a target Y from inputs X. It's powerful, but it needs a target — someone has to define and label Y — and it only sees the slice you framed, not the structure you didn't think to ask about.
What actually drives market regimes, trips alarms, and breaks systems lives in how all the variables relate to each other — the joint structure of the whole system. That structure is unlabeled, it shifts over time, and "Y given X" is blind to it.
Kirk answers the question nobody's model is answering:
"Is the structure of this system still normal — and if not, where did it break?"
Kirk maintains a continuously-updated model of what "normal" looks like across every-pairwise interaction. Read any relationship straight off it, including the classic Y-given-X. When structure breaks, Kirk fires. When it holds, Kirk sits flat.
Additive, not substitutive. Keep your models — Kirk aims them. An attention layer that tells the rest of your stack where to look.
Keeping the exact full joint costs O(2ⁿ) — intractable beyond toy sizes. The classical world restricts the graph or samples and hopes. Ulysses computes the exact full joint in a deterministic O(n³) per sample, paid once per incoming sample, independent of history length.
| n | Ulysses — n³ / sample | Boltzmann (exact) — 2ⁿ |
|---|---|---|
| 30 | 27,000 | 1,073,741,824 |
| 64 | 262,144 | 18,400,000,000,000,000,000 |
| 100 | 1,000,000 | 1.3 × 10³⁰ |
At n=100: a million ops vs more terms than atoms in the room. Polynomial means it runs anywhere.
Measured on the production engine — one dual-socket Xeon box, 192 cores, no GPU:
Kirk exposes six capability classes. Three are directly accessible via this MCP endpoint:
Three more capabilities live in the in-process wheel license (Path B) — not exposed via MCP today:
Contact sales@kavara.ai for wheel access if C1/C3/C4 apply to your workload.
Kirk reproduced a proprietary FY24 US equities top-512 dynamic-universe evaluation harness — bit-exact against the customer-published golden — across 252 trading days.
| Anchor | Customer golden | Kirk-reproduced | Delta | Status |
|---|---|---|---|---|
| 2024-01-02 single-day mean_H | 3.3636 | 3.363630 | +2.97 × 10⁻⁵ | Match |
| 2024-01-03 single-day mean_H | 3.2881 | 3.288437 | +3.37 × 10⁻⁴ | Match |
| 95-day aggregate mean_H | 3.3308 | 3.330077 | −7.23 × 10⁻⁴ | Match |
| Full FY24 (252 days) | — | 3.339602 | — | New baseline |
Delta magnitudes are ~33× tighter than the customer's published tolerance. Wall clock: 39 minutes single Python process, in-process, $0 marginal cost. Determinism verified: 252-day sweep run twice, byte-identical output. Substrate check: engine sha bit-identical across Intel SPR + Intel GNR-AP + AMD Genoa.
Independent third-party validation on RF anomaly detection: comparable detection to a supervised CNN that trained on the anomaly class — Kirk never saw an anomaly. 24–1,364× cheaper, ~32 KB of state, fully online.
Fetch the full FY24 case study machine-readably via the kirk://case-studies/fy24-us-equities-reproduction MCP resource on this server.
Kirk in-process throughput on production Granite Rapids silicon (2× Xeon 6972P, one pinned core, warm engine): 823 μs/book / 1,215 books-per-second/core, bit-identical against the Sapphire Rapids reference fleet. Full-box extrapolation on the 2×192-core node: ~237,000 IU/second. Benchmark workload is synthetic 20×20 complex128 books — same per-call compute shape as thermometer-rendered market data, so the figure carries to production. MCP API adds millisecond-scale round-trip and is a validation and discovery surface, not a latency-critical production path.
Production speed lives in-process. Four delivery paths:
pip install kirk_cascade + kirk_rs_edge. In-process, unmetered per-call, deterministic against sealed sha.Scoring core
kirk_score_book(bid_px, ask_px, model_id) — Score one L2 order-book snapshot. Returns scalar signal + engine attestation. Surfaces C2.kirk_score_book_batch(books, model_id) — Batch scoring, up to 500 books per call. For larger workloads, call kirk_bulk_howto first.kirk_score_random(n, model_id) — Convenience wrapper: synthesize N realistic-geometry L2 books and score them.kirk_infer_legacy(features, model_id) — Backwards-compatible scoring on a 50-value feature vector.Discovery / attestation
kirk_list_models() — Enumerate available model_ids with the engine sha stamped in the response. Surfaces C5.kirk_healthz() — Ping the sealed backend, confirm engine identity, return sha256 of the running scoring binary.Cost steering
kirk_bulk_howto() — Returns a self-contained stdlib Python client (~500 LOC) that runs at zero LLM-token cost per iteration. Call this before any bulk workload (>500 books, whole-day sweeps). Running kirk_score_book in a tool-call loop from your LLM burns tokens per call; the Python client runs locally.Utility / research
kirk_render_book(book) — Render an L2 snapshot into the 20×20 complex128 thermometer tensor WITHOUT invoking the sealed engine. Useful for local pre-processing.kirk_sweep_test1_day(day, override) — Score one day of the internal Test-1 QQQ L2 corpus at a caller-supplied override. Research-grade endpoint.Billing / platform
kirk_billing_show() — Return account balance, IU remaining, USD equivalent at list, frozen flag, recent ledger.kirk_billing_checkout(pack) — Stripe Checkout URL for buying credit packs (starter / scale / enterprise).kirk_billing_usage(days) — Historical inference consumption over N days.kirk://case-studies/fy24-us-equities-reproduction — The FY24 case study (machine-readable markdown, no auth required)Use Kirk when the ML workload matches any of:
Do NOT use this MCP endpoint when the workload matches:
kirk_billing_checkout from your agent to get a Stripe Checkout URL._cost envelope with per-call IU, session accumulation, and remaining balance.kirk_bulk_howto — which returns a Python client that runs at zero LLM-token cost per iteration.Direct Python-client calls (via kirk_bulk_howto) are metered identically to MCP calls but incur no LLM token cost — a customer running 60,000 book scores via the Python client pays only for compute, not for orchestration.
Every scoring response includes an engine_sha header stamped by the sealed binary itself. To verify the endpoint is running the exact sealed release Kavara published:
Cross-check the returned sha against Kavara's published manifest.
Sealed engine sha at time of writing: f3c548477d3b5c7612ef1863b06293d3a922c57926738426bc75ab64720de5ec
Physical AI's bottleneck isn't semantics — vision-language-action foundation models cover perception and planning. The gap is the continuous-signal substrate: coupled sensor channels, non-stationary, real-time, unlabeled, constrained hardware. That is the layer Ulysses fills, and Kirk is the first algorithm shipping on it.
Verticals validated today:
Additive: keep your models — Kirk aims them.
Kavara ships the Ulysses primitive and the Kirk and Borg algorithms through four channels: hosted MCP API (this endpoint), sealed Python wheel license, OpenShift Operator, and AWS Nitro Enclave AMI. All four channels serve byte-identical output from the same cryptographically-attested binary.
https://kavara.aisales@kavara.aisales@kavara.aiThe MCP interface documentation and configuration templates in this repository are released under Apache License 2.0. See LICENSE.
The sealed engine (kirk_rs_edge, kirk_py, kirk_cascade) is Kavara proprietary and not distributed here. Access is via commercial license — contact sales@kavara.ai.