Kirk — Unsupervised Structural Change Detection

kirk-mcp

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.

Using the Kirk API from Python, or setting it up with an AI agent? Use

[Kavara-AI/kirk-kit](https://github.com/Kavara-AI/kirk-kit): the released kit for https://api.kavara.ai,

with a key from kavara.ai/login. Agents: follow its

AGENTS.md. This repository documents the separate

MCP server only.

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.

Quick start

Fastest path: [paste this into your assistant](./SETUP.md) 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:

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):

{

"mcpServers": { "kirk": { "url": "https://kirk-mcp.kavara.ai/mcp", "headers": { "Authorization": "Bearer k_YOUR_PERSONAL_KEY" } } } }

Personal key, as a URL — for clients that accept only a URL (the Claude Desktop and claude.ai connector dialogs, for example):

{

"mcpServers": { "kirk": { "url": "https://kirk-mcp.kavara.ai/mcp/k_YOUR_PERSONAL_KEY" } } }

Service token, if that is what you hold:

{

"mcpServers": { "kirk": { "url": "https://kirk-mcp.kavara.ai/mcp", "headers": { "CF-Access-Client-Id": "YOUR_SERVICE_TOKEN_ID", "CF-Access-Client-Secret": "YOUR_SERVICE_TOKEN_SECRET" } } } }

Command-line clients that take flags rather than JSON, such as Claude Code:

claude mcp add --transport http kirk https://kirk-mcp.kavara.ai/mcp \

-H "Authorization: Bearer k_YOUR_PERSONAL_KEY"

Sign in at kavara.ai to create a key. Scoring tools use credits; kirk_billing_show shows your balance.

Check it worked

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.

Troubleshooting

• A 403 that looks like an authentication failure. Often it is the 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.
• A 402. The account balance is exhausted. Call kirk_billing_show.
• A model listed by `kirk_list_models` that errors when called. The catalogue lists registered models; it is not a liveness check. Please report it.

What most machine learning does today, and what Kirk does instead

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.

Why nobody else keeps the whole graph

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.

At n=100: a million ops vs more terms than atoms in the room. Polynomial means it runs anywhere.

Between a Kalman filter and a GPU deep net

Measured on the production engine — one dual-socket Xeon box, 192 cores, no GPU:

• 2.66M model updates / second (cascade layer 1: 402k/s; cascade layer 2: 66.7k/s)
• 6m 38s for a full year of S&P-500 minute bars, 10-seed ensemble (~14.7 CPU-hours of work, one box, no GPU)
• O(n³) per sample, not O(2ⁿ) — polynomial, scales to thousands of models
• Runs inside confidential (Intel TDX / AWS Nitro / AMD SEV) enclaves — your data never leaves your environment, and the engine never leaves ours

What you get from this MCP endpoint

Kirk exposes six capability classes. Three are directly accessible via this MCP endpoint:

• C2 — Cross-section structural scoring on variable-universe panels. Score a snapshot against a learned normal and emit a scalar. N can vary across calls without retraining — the primitive is shape-agnostic.
• C5 — Cryptographic attestation of engine identity. Every scoring output is verifiable against the exact sealed binary that produced it.
• C6 — Determinism across substrates. Bit-exact identical output across Intel Sapphire Rapids, Intel Granite Rapids, and AMD Genoa. No floating-point nondeterminism.

Three more capabilities live in the in-process wheel license (Path B) — not exposed via MCP today:

• C1 — Structural merging. Combine two learned "normals" from disjoint slices into a unified picture, preserving the joint spectrum.
• C3 — Stateful drift detection. Model absorbs new observations into its state and emits signal that reflects distributional drift. No retraining; state evolves in-place.
• C4 — Higher-order correlation detection at noise floor. Signal from higher-order joint distributions where Kalman filters, PCA, and linear regression are at their sensitivity floor. Independently verified by a quant firm at ~16× the linear baseline.

Contact sales@kavara.ai for wheel access if C1/C3/C4 apply to your workload.

What Kirk is NOT

• Not a foundation model. No pretraining corpus, no weights. The IP is the math.
• Not a trading strategy. Kirk emits structural change signal; how to act on it is your decision.
• Not an HFT execution engine. MCP round-trip is millisecond-scale. Production speed lives in-process (Path B/C/D below).
• Not validated on every data type. Heavy validation on financial L2 books and financial panels. RF spectrum and coordinated-behavior fraud detection are additional validated domains. Other domains (images, text, general tensors) require per-domain characterization first — contact us before assuming Kirk generalizes to your domain.

Correctness — validated on real markets

Kirk reproduced a proprietary FY24 US equities top-512 dynamic-universe evaluation harness — bit-exact against the customer-published golden — across 252 trading days.

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.

In-process throughput (measured separately)

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 credits/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:

• Path A — MCP API (this endpoint). Discovery, validation, and pay-as-you-go per-call.
• Path B — Sealed wheel license. pip install kirk_cascade + kirk_rs_edge. In-process, unmetered per-call, deterministic against sealed sha.
• Path C — OpenShift Operator. Kavara-shipped Operator on the customer's own cluster. Enterprise. Trustee attestation.
• Path D — AWS Nitro Enclave AMI. Currently shipping to enterprise customers via AWS Marketplace private offers. PCR0-attested.

Tools available on this MCP endpoint

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