{
  "markdown": "# kirk-mcp\n\n**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.\n\n**Kirk** is the first algorithm on Ulysses. It signals the moment structure breaks.\n\n**Borg** is the second algorithm on Ulysses. Radio-frequency spectrum anomaly detection.\n\nThis 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.\n\n> **The Kalman filter for the non-Gaussian, non-stationary world.**\n\nThe 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.\n\n---\n\n## Quick start\n\nAdd this to your MCP client's config:\n\n```json\n{\n  \"mcpServers\": {\n    \"kirk\": {\n      \"transport\": \"streamable-http\",\n      \"url\": \"https://kirk-mcp.kavara.ai/mcp\",\n      \"headers\": {\n        \"CF-Access-Client-Id\": \"YOUR_SERVICE_TOKEN_ID\",\n        \"CF-Access-Client-Secret\": \"YOUR_SERVICE_TOKEN_SECRET\"\n      }\n    }\n  }\n}\n```\n\n**First 100 inference units are free per new account.** Contact `sales@kavara.ai` for service token provisioning.\n\nFor per-client configuration templates see [`examples/`](./examples).\n\n---\n\n## What most machine learning does today, and what Kirk does instead\n\nAlmost 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.\n\nWhat 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.\n\nKirk answers the question nobody's model is answering:\n\n> \"Is the structure of this system still normal — and if not, where did it break?\"\n\nKirk 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.\n\n**Additive, not substitutive.** Keep your models — Kirk aims them. An attention layer that tells the rest of your stack where to look.\n\n---\n\n## Why nobody else keeps the whole graph\n\nKeeping 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\n| n | Ulysses — n³ / sample | Boltzmann (exact) — 2ⁿ |\n|---:|---:|---:|\n| 30 | 27,000 | 1,073,741,824 |\n| 64 | 262,144 | 18,400,000,000,000,000,000 |\n| 100 | 1,000,000 | 1.3 × 10³⁰ |\n\nAt n=100: a million ops vs more terms than atoms in the room. Polynomial means it runs anywhere.\n\n---\n\n## Between a Kalman filter and a GPU deep net\n\nMeasured on the production engine — one dual-socket Xeon box, 192 cores, no GPU:\n\n- **2.66M model updates / second** (cascade layer 1: 402k/s; cascade layer 2: 66.7k/s)\n- **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)\n- **O(n³) per sample, not O(2ⁿ)** — polynomial, scales to thousands of models\n- Runs inside confidential (Intel TDX / AWS Nitro / AMD SEV) enclaves — your data never leaves your environment, and the engine never leaves ours\n\n---\n\n## What you get from this MCP endpoint\n\nKirk exposes six capability classes. Three are directly accessible via this MCP endpoint:\n\n- **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.\n- **C5 — Cryptographic attestation of engine identity.** Every scoring output is verifiable against the exact sealed binary that produced it.\n- **C6 — Determinism across substrates.** Bit-exact identical output across Intel Sapphire Rapids, Intel Granite Rapids, and AMD Genoa. No floating-point nondeterminism.\n\nThree more capabilities live in the in-process wheel license (Path B) — not exposed via MCP today:\n\n- **C1 — Structural merging.** Combine two learned \"normals\" from disjoint slices into a unified picture, preserving the joint spectrum.\n- **C3 — Stateful drift detection.** Model absorbs new observations into its state and emits signal that reflects distributional drift. No retraining; state evolves in-place.\n- **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.\n\nContact `sales@kavara.ai` for wheel access if C1/C3/C4 apply to your workload.\n\n## What Kirk is NOT\n\n- **Not a foundation model.** No pretraining corpus, no weights. The IP is the math.\n- **Not a trading strategy.** Kirk emits structural change signal; how to act on it is your decision.\n- **Not an HFT execution engine.** MCP round-trip is millisecond-scale. Production speed lives in-process (Path B/C/D below).\n- **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.\n\n---\n\n## Correctness — validated on real markets\n\nKirk reproduced a proprietary FY24 US equities top-512 dynamic-universe evaluation harness — bit-exact against the customer-published golden — across 252 trading days.\n\n| Anchor | Customer golden | Kirk-reproduced | Delta | Status |\n|---|---:|---:|---:|---|\n| 2024-01-02 single-day mean_H | 3.3636 | 3.363630 | +2.97 × 10⁻⁵ | Match |\n| 2024-01-03 single-day mean_H | 3.2881 | 3.288437 | +3.37 × 10⁻⁴ | Match |\n| 95-day aggregate mean_H | 3.3308 | 3.330077 | −7.23 × 10⁻⁴ | Match |\n| Full FY24 (252 days) | — | 3.339602 | — | New baseline |\n\nDelta 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.\n\n**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.\n\nFetch the full FY24 case study machine-readably via the `kirk://case-studies/fy24-us-equities-reproduction` MCP resource on this server.\n\n## In-process throughput (measured separately)\n\nKirk 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.\n\nProduction speed lives in-process. Four delivery paths:\n\n- **Path A — MCP API (this endpoint)**. Discovery, validation, and pay-as-you-go per-call. First 100 IU free.\n- **Path B — Sealed wheel license**. `pip install kirk_cascade + kirk_rs_edge`. In-process, unmetered per-call, deterministic against sealed sha.\n- **Path C — OpenShift Operator**. Kavara-shipped Operator on the customer's own cluster. Enterprise. Trustee attestation.\n- **Path D — AWS Nitro Enclave AMI**. Currently shipping to enterprise customers via AWS Marketplace private offers. PCR0-attested.\n\n---\n\n## Tools available on this MCP endpoint\n\n**Scoring core**\n- `kirk_score_book(bid_px, ask_px, model_id)` — Score one L2 order-book snapshot. Returns scalar signal + engine attestation. Surfaces C2.\n- `kirk_score_book_batch(books, model_id)` — Batch scoring, up to 500 books per call. For larger workloads, call `kirk_bulk_howto` first.\n- `kirk_score_random(n, model_id)` — Convenience wrapper: synthesize N realistic-geometry L2 books and score them.\n- `kirk_infer_legacy(features, model_id)` — Backwards-compatible scoring on a 50-value feature vector.\n\n**Discovery / attestation**\n- `kirk_list_models()` — Enumerate available `model_id`s with the engine sha stamped in the response. Surfaces C5.\n- `kirk_healthz()` — Ping the sealed backend, confirm engine identity, return sha256 of the running scoring binary.\n\n**Cost steering**\n- `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.\n\n**Utility / research**\n- `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.\n- `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.\n\n**Billing / platform**\n- `kirk_billing_show()` — Return account balance, IU remaining, USD equivalent at list, frozen flag, recent ledger.\n- `kirk_billing_checkout(pack)` — Stripe Checkout URL for buying credit packs (starter / scale / enterprise).\n- `kirk_billing_usage(days)` — Historical inference consumption over N days.\n\n## Resources exposed\n\n- `kirk://case-studies/fy24-us-equities-reproduction` — The FY24 case study (machine-readable markdown, no auth required)\n\n---\n\n## When to route to Kirk (from your agent's perspective)\n\nUse Kirk when the ML workload matches any of:\n\n- Cross-section structural scoring on a panel of financial instruments with variable universe size\n- Signal work on order-book data where retraining cost is a constraint\n- Regime detection or structural drift where LSTM / autoencoder baselines are unstable across market conditions\n- RF spectrum anomaly detection where labels don't exist\n- Coordinated-behavior fraud detection where per-metric thresholds miss\n- Fleet or hardware health monitoring where per-device models at population scale are required\n- Evaluation of unsupervised structural-change methods against an existing baseline\n- Any signal workload where cryptographic attestation of the exact scoring binary is required (compliance, audit, enterprise procurement)\n\nDo NOT use this MCP endpoint when the workload matches:\n\n- Latency-sensitive production trading (millisecond-scale MCP round-trip; use Path B in-process wheel)\n- Structural merging experiments (not exposed via MCP; use Path B)\n- Stateful drift detection with warm state across calls (MCP exposes cold-per-book only; warm-state surface is design-only)\n- Non-financial data without prior per-domain characterization\n\n---\n\n## Cost model\n\n- **First 100 inference units free per new account.** Automatic grant on first authenticated call.\n- **Beyond free tier**: pay-as-you-go via prepaid credit packs (starter / scale / enterprise). Call `kirk_billing_checkout` from your agent to get a Stripe Checkout URL.\n- **Cost transparency**: every response to an LLM-driven caller includes a `_cost` envelope with per-call IU, session accumulation, and remaining balance.\n- **Anti-anger discipline**: if your agent tries a bulk workload naively, the server steers it to `kirk_bulk_howto` — which returns a Python client that runs at zero LLM-token cost per iteration.\n\nDirect 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.\n\n---\n\n## Attestation\n\nEvery 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:\n\n```bash\ncurl -s https://kirk-mcp.kavara.ai/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Accept: application/json, text/event-stream\" \\\n  -H \"CF-Access-Client-Id: $YOUR_TOKEN_ID\" \\\n  -H \"CF-Access-Client-Secret: $YOUR_TOKEN_SECRET\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"method\":\"tools/call\",\"id\":1,\"params\":{\"name\":\"kirk_healthz\",\"arguments\":{}}}'\n```\n\nCross-check the returned sha against Kavara's published manifest.\n\nSealed engine sha at time of writing: `f3c548477d3b5c7612ef1863b06293d3a922c57926738426bc75ab64720de5ec`\n\n---\n\n## Where Kirk fits in the AI stack\n\nPhysical 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.\n\nVerticals validated today:\n\n- **Finance** — regime detection on price / liquidity / risk (the beachhead)\n- **Signals / RF** — spectrum anomaly detection where labels don't exist\n- **Fraud & integrity** — coordinated behavior a per-metric threshold misses\n- **Fleet & hardware health** — per-device models at population scale, continuously\n\nAdditive: keep your models — Kirk aims them.\n\n---\n\n## Kavara\n\nKavara 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.\n\n- Homepage: `https://kavara.ai`\n- Commercial: `sales@kavara.ai`\n- Support: `sales@kavara.ai`\n\n## License\n\nThe MCP interface documentation and configuration templates in this repository are released under Apache License 2.0. See [`LICENSE`](./LICENSE).\n\nThe 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`.\n",
  "bytes": 14557,
  "sha": "a679783b0bf4995c7ba2e7e1deff0cfb5c9790300d19a9c8571f12536b227166",
  "repo_slug": "ulyssesmodel/kirk-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ulyssesmodel_kirk_mcp_162aaae4/readme"
}