# Kirk — Unsupervised Structural Change Detection

> The Kalman filter for the non-Gaussian, non-stationary world. Unsupervised structural change.

- name: io.github.UlyssesModel/kirk-mcp
- version: 1.0.2
- connection class: R1 (autonomous)
- trust: 87/100
- quality: 82/100 (good)
- owner: not claimed
- descriptor: https://api.protogrid.dev/v1/servers/io.github.UlyssesModel%2Fkirk-mcp
- tools: https://api.protogrid.dev/v1/servers/io.github.UlyssesModel%2Fkirk-mcp/tools

**An agent can connect on its own if it already holds `CF_ACCESS_CLIENT_ID`, `CF_ACCESS_CLIENT_SECRET`, `CF_ACCESS_CLIENT_ID`.** Remote endpoint behind a static API key or header. The registry never sees the value; the agent fills the placeholder.

## Connection (mcpServers)

```json
{
  "mcpServers": {
    "kirk-mcp": {
      "type": "http",
      "url": "https://kirk-mcp.kavara.ai/mcp",
      "headers": {
        "CF-Access-Client-Id": "${CF_ACCESS_CLIENT_ID}",
        "CF-Access-Client-Secret": "${CF_ACCESS_CLIENT_SECRET}",
        "Authorization": "${CF_ACCESS_CLIENT_ID}"
      }
    }
  }
}
```

Placeholders to fill: `${CF_ACCESS_CLIENT_ID}`, `${CF_ACCESS_CLIENT_SECRET}`, `${CF_ACCESS_CLIENT_ID}`.

## Trust

- hygiene: 100
- liveness: 100
- freshness: 65
- provenance: 80
- drivers: +repository +namespace-matches-repo +reachable +uptime-100% ~updated-91d-ago
- Derived from observable signals (official registry feed and our own credential-free probes); no code audit performed.

## Quality 82/100 (good)

### protocol: 75 (weight 25)

- warn `protocol.modern`: newest supported version is 2025-11-25; 2026-07-28 not supported, older versions are deprecated until 2027-07-28
- n/a `protocol.stateless`: only applies to 2026-07-28 servers
- pass `protocol.transport`: streamable HTTP
- n/a `protocol.list_ttl`: only applies to 2026-07-28 servers

### authorization: n/a (weight 15)

- n/a `auth.prm`, `auth.as_metadata`, `auth.cimd`: no remote uses OAuth
- n/a `auth.secret_in_url`: no templated URL

### tool hygiene: 79 (weight 30)

- pass `tools.descriptions`: every tool has a description
- warn `tools.description_length`: 7 tools have descriptions over 1,024 characters, which crowds the context
- pass `tools.schemas`: every tool has an object input schema
- pass `tools.annotations`: 14 of 14 tools declare readOnlyHint or destructiveHint
- fail `tools.directory_hints`: no tool declares all four of readOnlyHint, destructiveHint, idempotentHint and openWorldHint; missing: kirk_score_l2_book (idempotentHint); kirk_billing_checkout (idempotentHint); kirk_billing_usage (idempotentHint); …
- pass `tools.token_cost`: about 5,223 tokens to load every tool
- pass `tools.api_dump`: tools are not a one-to-one API dump

### stability: 100 (weight 15)

- pass `stability.changes`: no tool changes in 30 days
- pass `stability.rug_pull`: no tool changed its meaning under the same name

### dependencies: n/a (weight 15)

- n/a `deps.known_vulns`, `deps.mcp_sdk_version`, `deps.resolvable`: no npm or PyPI package

- tools: 14, about 5,223 tokens to load them all
- tool set hash: fa370785ba7137f3f18b79ab6ab7987d
- badge: [![protogrid quality](https://protogrid.dev/badge/io.github.UlyssesModel/kirk-mcp.svg)](https://protogrid.dev/servers/io.github.UlyssesModel/kirk-mcp)
- Checks run on what our credential-free, read-only probes observe; tools are never called and no code audit is performed.

### Tool changes

_No tool definition changes recorded._

## Remotes

- https://kirk-mcp.kavara.ai/mcp (streamable-http, auth api_key ${CF_ACCESS_CLIENT_ID}, reachable true, uptime30d 1)

## Packages

_none_

## Tools (14)

- `kirk_billing_checkout`: Create a Stripe Checkout Session URL for buying a credit pack (starter / scale / enterprise).

Purpose: Hand the caller a self-serve URL to purchase IU credits.

Use when: The caller's balance is low, or you want to route to
a self-serve top-up flow before a larger validation batch.

Do not use when: The caller is on an enterprise in-process
deployment — those are invoiced directly, not via Checkout.

Capability class(es): Meta (billing).

Path fit: MCP only.

Cost: 0 IU. Callable at balance=0.
- `kirk_billing_show`: Return the caller's account_id, IU balance, USD equivalent at list, frozen flag, and recent ledger entries.

Purpose: Surface the caller's current billing state — what they
can spend, whether the account is frozen, and how recent entries
landed.

Use when: The caller wants to check available credit before
committing to a large batch, or you are debugging a
"why-was-I-charged" question.

Do not use when: You just need per-call cost — the `_cost`
envelope on every agent-driven tool result carries that inline
without a separate call.

Capability class(es): Meta (account state), not a capability of
the scoring engine.

Path fit: MCP only. Enterprise in-process deployments have
their own billing surface (invoiced separately).

Cost: 0 IU. Callable at balance=0 so a customer with zero credit
can still self-serve to top up.
- `kirk_billing_usage`: Return the caller's inference consumption over the last N days from the append-only Gate 2 events table.

Purpose: Historical usage summary + per-tool breakdown for the
caller's account.

Use when: You need a usage report for the caller or an admin,
or you are reconciling ledger debits against actual inference
events.

Do not use when: You need real-time cost — the `_cost` envelope
on every agent-driven tool result covers that inline.

Capability class(es): Meta (metering).

Path fit: MCP only.

Cost: 0 IU.
- `kirk_bulk_howto`: Return a self-contained stdlib Python client for scoring at ZERO per-call LLM tokens.

Purpose: Hand the caller an HTTP consumer that runs locally so
bulk scoring doesn't burn LLM tokens per book.

Use when: You need to score more than ~200 books, or
`kirk_score_book_batch` returned `batch_too_large`, or the caller
is running an autonomous bulk workload that would otherwise pay
per-tool-call LLM tokens for every book.

Do not use when: You are running a one-off interactive call — a
direct `kirk_score_book` invocation is simpler; don't route
through the client for a single book.

Capability class(es): Cost-steering / delivery-path tool. Hands
the caller a runner that exercises the same C2 / C5 / C6
capabilities as the MCP scoring tools, but at zero per-call LLM
token cost.

Path fit: The returned client is an HTTP consumer of the same
MCP endpoint. Production integrations run in-process under
sealed-engine attestation — same binary sha as this endpoint.
Contact Kavara for deployment options.

Cost: 0 IU. Free tool. Once running locally, the returned
client bills against the same tools it drives: single-book
calls at 1 IU each, and batch calls at 1 IU per 50 books
(minimum 1 IU per call). A full 500-book batch → 10 IU. No
LLM tokens on top.

Cost comparison (2.7M-book validation rerun via 500-book
batches — ~5400 batches, 54000 IU billed either way):
    MCP via Sonnet 5:            $1,968 LLM + $540 IU + ~15 days wall clock
    MCP via Haiku 4.5:             $656 LLM + $540 IU + ~10 days
    Python client (this tool):        $0 LLM + $540 IU + ~55 min

Return structure:
    {
      "language":     "python",
      "filename":     "kirk_online_client.py",
      "requirements": str,
      "usage":        str,
      "code":         str  (the client source, ~500 LOC),
      "example":      str  (2-line copy-paste demo)
    }
- `kirk_demo_trading`: Runs a curated demonstration of Kirk on a trading example. Zero arguments. Returns real Kirk output against the same sealed engine that customer callers hit. Free, rate-limited. First-time users: call this to see what Kirk does before signing up.

Purpose: Score n=30 jittered L2 snapshots per market regime
(stationary vs stressed) through the sealed engine and surface
the per-regime score-distribution statistics (mean, sd) plus the
z-separation between the two distributions in pooled-sd units.
Also carries a representative canonical book pair so callers
see two concrete scores alongside the distributions.

Use when: You are a first-time caller exploring what Kirk does.
You want a zero-friction "what does the output look like"
experience against real sealed-engine attestation.

Do not use when: You are scoring your own data — use
``kirk_score_book`` or ``kirk_score_book_batch``. This tool's
input is a fixed synthetic representative pair, not a market
feed.

Capability class(es): C2 (variable-universe cross-section entropy
scoring) demonstrated end-to-end against the sealed engine.

Path fit: MCP demonstration surface only.

Cost: 0 IU. Rate-limited 3/hour per IP.

Returns:
    Dict with per-regime ``stationary`` and ``stressed`` blocks
    (each: ``mean``, ``sd``, ``n``, ``kirk_version``),
    ``z_separation`` (pooled-sd distance between the two
    regime distributions), ``representative_pair`` (canonical
    un-jittered ``stationary_score`` / ``stressed_score`` plus
    ``book_summaries``), ``interpretation_hint``, ``provenance``,
    and ``synthetic_representative`` flag.
- `kirk_demo_uav`: Runs a curated demonstration of Kirk on a UAV example. Zero arguments. Returns real Kirk output against the same sealed engine that customer callers hit. Free, rate-limited. First-time users: call this to see what Kirk does before signing up.

Purpose: Score n=30 jittered 50-element spectra per acoustic
class (drone / bird / helicopter) through the sealed engine
and surface per-class score-distribution statistics plus
z-separations for the three class pairs. Demonstrates that the
same sealed engine sha handles market microstructure and
acoustic spectra with the same primitive.

Use when: You want to see Kirk's cross-domain generalization
without needing your own audio dataset.

Do not use when: You have real feature vectors to score — use
``kirk_infer_legacy`` directly (arg: list of 50 floats). This
tool's inputs are fixed synthetic spectra baked into the demo.

Capability class(es): Demonstrates domain-agnostic mathematical
primitive — the same engine sha handles kirk_score_book (L2)
and kirk_infer_legacy (arbitrary 50-vector).

Path fit: MCP demonstration surface only.

Cost: 0 IU. Rate-limited 3/hour per IP.

Returns:
    Dict with per-class ``drone`` / ``bird`` / ``helicopter``
    blocks (each: ``mean``, ``sd``, ``n``, ``kirk_version``),
    ``z_separation`` (dict of drone_vs_bird / drone_vs_helicopter
    / bird_vs_helicopter in pooled-sd units),
    ``representative_scores`` (the three single-sample scores
    from the canonical un-jittered spectra),
    ``interpretation_hint``, ``provenance``, and
    ``synthetic_spectral`` flag.
- `kirk_infer_legacy`: Score a 50-value feature vector against the legacy /v1/infer route on the sealed engine.

Purpose: Backwards-compatible scoring surface for callers that were
already targeting the legacy path.

Use when: You have an existing client wired to /v1/infer and need
continued MCP access without refactoring.

Do not use when: You are on a fresh integration — prefer kirk_score_book
(single-layer, cascade-shaped path). Also do not use in a tight loop
against a large corpus: the MCP round-trip is millisecond-scale, and
the LLM tool-call cost accrues per book for agent-driven callers.
For bulk work, call kirk_bulk_howto first.

Capability class(es): C2 (cross-section entropy scoring), legacy
interface.

Path fit: Validation via MCP (this tool). Production integrations
run in-process under sealed-engine attestation — same binary sha as
this endpoint. Contact Kavara for deployment options.

Cost: 1 IU per call. For agent-driven callers, per-call LLM tokens
accrue on top; the response _cost envelope surfaces both.
- `kirk_list_models`: Enumerate the model_ids the sealed engine exposes, with the engine sha stamped in-response.

Purpose: Discover the model catalog and record the sealed engine sha
alongside your inference results.

Use when: You are wiring a client for the first time and need model_id
values for kirk_score_book / kirk_score_book_batch calls, or you want a
machine-readable catalog with attestation.

Do not use when: You need per-model hyperparameter detail — those are
intentionally not exposed on the customer surface.

Capability class(es): C5 (engine sha attested on every response).

Path fit: Validation via MCP (this tool). Production integrations
run in-process under sealed-engine attestation — same binary sha as
this endpoint. Contact Kavara for deployment options.

Cost: 0 IU. Free tool.
- `kirk_render_book`: Render an L2 order-book snapshot into the 20×20 complex128 thermometer tensor WITHOUT invoking the sealed engine.

Purpose: Local tensor prep and inspection — see what shape the
sealed engine will receive without paying for a scoring call.

Use when: You want to sanity-check bid/ask level convention against
the model's canonical input convention, inspect the non-zero cell
pattern for a snapshot, or debug an unexpected entropy value by
first confirming the tensor is well-formed.

Do not use when: You need an entropy score — this tool is prep-only.
Call kirk_score_book to score.

Capability class(es): Local prep for the C2 (variable-universe
cross-section entropy) workflow. No sealed-engine interaction; no
capability class is exercised beyond the input-shape convention.

Path fit: Validation via MCP (this tool). The same tensor shape is
what production in-process integrations consume under sealed-engine
attestation.

Cost: 0 IU. Free tool.
- `kirk_score_book`: Score one L2 order-book snapshot through the sealed single-layer path and return a scalar entropy plus engine attestation.

Purpose: Score one snapshot end-to-end through the sealed engine and
surface the result plus the engine sha that produced it.

Use when: You are validating Kirk on your own data before committing
to a production path, or you are scoring a single snapshot inside an
interactive workflow (rate-limited at 60 req/min per account).

Do not use when: You need throughput above interactive scale, or you
are in a per-book loop from an LLM. MCP round-trip is millisecond-scale
and inappropriate for latency-critical work. For >200 books, call
kirk_bulk_howto first — the returned stdlib Python client scores at
zero LLM tokens per iteration.

Capability class(es):
- C2 (variable-universe cross-section entropy scoring — same model
  handles any N without retraining).
- C5 (sealed engine sha stamped on every response).
- C6 (bit-exact reproducibility across substrates; validated by the
  FY24 252-day reproduction, byte-identical on repeat runs).

Path fit: Validation via MCP (this tool). Production integrations
run in-process under sealed-engine attestation — same binary sha as
this endpoint. Contact Kavara for deployment options. MCP is a
validation and discovery surface, not a latency-critical production
path.

Cost: 1 IU per call. LLM tokens accrue on top for agent-driven callers.
- `kirk_score_book_batch`: Score up to 500 L2 order-book snapshots in one MCP call — returns an entropies list plus engine attestation.

Purpose: Batch-score up to 500 snapshots through the sealed engine in
a single MCP dispatch.

Use when: You are validating batch behaviour, comparing entropy
distributions across small book sets, or running interactive
experiments up to 500 books at a time.

Do not use when: You have more than 500 books, or you are looping
this tool from an LLM. Batches >500 raise a structured
`batch_too_large` before any ledger debit. For sustained bulk work,
call kirk_bulk_howto — the stdlib Python client scores at zero LLM
tokens per iteration.

Capability class(es):
- C2 (variable-universe cross-section entropy — heterogeneous batch
  shapes are handled by one model without retraining).
- C5 (sealed engine sha stamped on every response).
- C6 (bit-exact reproducibility across substrates and runs).

Path fit: Validation via MCP (this tool). Production bulk workloads
run in-process under sealed-engine attestation — same binary sha as
this endpoint. Contact Kavara for deployment options. The MCP
round-trip is inappropriate for high-throughput consumption.

Cost: 1 IU per 50 books (minimum 1 IU per call). n≤50 → 1 IU;
n=51..100 → 2 IU; a full 500-book batch → 10 IU. Validation tier —
validation-scale limits. LLM-agent-scoped cap at 500 books; use
kirk_bulk_howto for anything larger.
- `kirk_score_l2_book`: Score a sequence of full L2 order books as one chain and return per-book entropies plus engine attestation.

Purpose: Score complete books — prices, sizes and order counts — rather than
prices alone. This is the v2 book contract; it carries information the
price-only contract cannot.

STATE POLICY, and it matters: the books are scored IN ORDER as a single
fresh chain. The model starts from its locked initial state at the first
book and carries state forward across the rest, so a book's value depends
on the books before it. State is never carried between calls. Sending the
same books in a different order is a different measurement and will return
different values; scoring N books one-per-call is NOT equivalent to one
call of N books.

Use when: You are validating Kirk on full L2 snapshots. For the price-only
v1 contract use kirk_score_book — the two are different envelopes and are
not interchangeable.

Do not use when: You are looping this tool from an LLM. Call kirk_bulk_howto
for bulk work; its v2 mode wraps this same call.

Cost: 1 IU per call.
- `kirk_score_random`: Synthesize N realistic-geometry L2 book snapshots and score them — convenience wrapper on kirk_score_book_batch.

Purpose: Produce a live entropy series with no external data — the
fastest way to confirm a new integration is wired end-to-end.

Use when: You want a wiring-check, a first-integration walk-through,
or a quick reference for the response shape without needing to
supply your own market data.

Do not use when: You are scoring anything real — feed your own data
through kirk_score_book_batch. Synthetic bids/asks are not benchmark
input and should not appear in customer-visible results.

Capability class(es): C2 (uses the same variable-universe cross-
section entropy path as kirk_score_book_batch, on synthetic input).

Path fit: Validation via MCP (this tool). Not a production surface.

Cost: 1 IU per invocation. Internally routes through
kirk_score_book_batch — one metered dispatch, no double-metering.
- `kirk_verify_engine`: Verify sealed engine identity — returns the sha256 of the running scoring binary. Also serves as a liveness probe against the sealed backend.

Purpose: Attest which Kirk build is currently serving scoring calls.
Response carries the HOST DEFAULT engine sha (kirk_version). That is the
legacy default and is NOT necessarily the engine that will stamp a given
kirk_score_* result: each model row in kirk_list_models identifies its own
engine, and every scoring response restates it under engine.sha. For a
model bound to a non-default engine (kirk-market-orderbook-v1) these
differ. Record the per-model value for provenance, not this one.
Secondary role: a cheap liveness probe when wiring up MCP.

Use when: You want to record engine sha in your own provenance log
before capturing scoring output, or you want a cheap liveness check
ahead of a larger validation batch.

Do not use when: You want a scoring result — this returns
identity/liveness only, no entropies.

Capability class(es): C5 (cryptographic attestation of engine identity).

Path fit: Validation via MCP (this tool). Production integrations
run in-process under sealed-engine attestation — same binary sha as
this endpoint. Contact Kavara for deployment options.

Cost: 0 IU. Free tool. For agent-driven callers, the _cost envelope
still reports iu_this_call=0 and the running session totals.

Returns:
    Dict with `status`, `engine`, `env`, and `kirk_version` (the
    sealed .so sha). A non-2xx response raises; caller sees a
    clean MCP tool error.