Skip to main content

title: Hatun MCP — Governed Agent Gateway emoji: 🪢 colorFrom: indigo colorTo: blue sdk: docker app_port: 7860 pinned: false license: apache-2.0 short_description: Source-bound MCP gateway with governance receipts

License Doctrine v11 LOCKED CI SLSA

🪢 hatun-mcp

The great context protocol — hatun (Quechua) = "big / great".

The one MCP endpoint that aggregates the SZL backend services — the a11oy command platform (and its live immune, companion and llm-router organs) plus killinchu (drones & vessels) — under PURIQ governance and re-exposes their tools to any MCP client. Receipts are DSSE-signed only when an operator signing key is configured; without one the signer runs in explicit PLACEHOLDER mode and /readyz reports not_ready (see signing).

Hatun Gateway · GitHub Org · LLM Router

Canonical runtime source. This repository owns the Python gateway, governed tool catalog, Streamable HTTP transport, and container contract. The standalone Hatun Hugging Face publisher was retired on September 3, 2026; hf-deploy must not be recreated. The public product experience is Hatun Gateway, which is not itself proof that this package's /mcp/ endpoint or a newly added tool is deployed. See the surface contract. The monorepo copy at platform/packages/hatun-mcp is a non-canonical embedded copy (it carries CANONICAL.md pointing here) that exposes a smaller tool set for local imports and must not diverge from this server's contracts. Folding the platform copy in is a later founder step; repos are not deleted here. Λ = Conjecture 1 (advisory) is preserved verbatim.

SZL Holdings — Orbit v2

Control before action. Evidence after.

Product · Proof · GitHub organization

receipts.in ≡ receipts.out


What this is

A real, operational Model Context Protocol server built on the official mcp Python SDK 2.x (mcp.server.mcpserver.MCPServer, formerly FastMCP). Every tool call is governed by the PURIQ formula:

  1. Authenticate the client (SZL API key → client_id, or, when the operator enables it, a Cloudflare x402 PAYMENT-CONTEXT verified at this origin → x402:<digest>); anonymous calls are declined.
  2. Yuyay-13 gate on the input (input-as-data; OWASP MCP06 injection defense).
  3. Reputation factor Hatun_MCP(client) ∈ [0,1].
  4. 2-person Yuyay gate for state-changing tools (e.g. killinchu_cue, halt_drone).
  5. Call the real organ backend within a latency budget.
  6. Mint a Khipu receipt on success and failure (append-only sha256 DAG).
  7. Return a DSSE-signed response — the client receives the receipt hash.

Choose your route

Audience Start here Evidence boundary
Developer Run locally, then inspect tools/list Local startup proves only the local process; backend reachability is separate
Integrator MCP client setup The checked-in client configuration is SAMPLE and does not include credentials
Evaluator Hosted health contracts, then Tests /healthz is liveness; /readyz is signed-release readiness; neither is an uptime guarantee

KANCHAY status contract

  • LIVE: a runtime-backed route with source and observation time. It never means perpetual availability.
  • PARTIAL: Hatun is locally ready, but one or more required upstream organ observations are missing, stale, or degraded.
  • SAMPLE: checked-in configuration, payload, or transcript for reuse; not observed runtime evidence.
  • SIMULATED: a mocked backend or hermetic test fixture. CI intentionally uses these where external services would make tests nondeterministic.
  • UNAVAILABLE: the dependency or readiness check cannot produce a usable result. Preserve the reason and do not substitute sample data.

Tools exposed

  • 37 static tools registered at import (verifiable: tools/list returns 37 with HATUN_MCP_DISABLE_DYNAMIC=true):
    • 31 szl_* tools — szl_a11oy_code_chat, szl_a11oy_operator_reason, szl_a11oy_sentinel_scan, szl_anatomy_3d_render, szl_doctrine_lookup, szl_drone_lookup, szl_battery_score, szl_formula_evaluate, szl_frontier_chain_read, szl_github_estate_snapshot, szl_holo_cells, szl_khipu_verify, szl_killinchu_cue, szl_killinchu_detect, szl_lean_verify, szl_puriq_evaluate, szl_companion_reason, szl_immune_scan, szl_thesis_query, szl_wayra_recent, szl_yachay_dome_predict, szl_yuyay_score, and szl_lambda_quorum (Byzantine Λ verdict); v9 (2026-11-15) AXLE bridge — szl_axle_status, szl_axle_environments, szl_axle_verify_proof, szl_axle_check, szl_axle_disprove, szl_axle_sorry2lemma, szl_axle_extract_proof_states, szl_axle_call (AxiomMath's AXLE Lean-verification surface consolidated as SECONDARY-oracle tools: corroborate, never authorize; fail-closed abstain; fixed allowlist, no redirects, bounded I/O, key never echoed).

      Two tools were renamed 2026-06-16 to honest organ names — szl_immune_scan (was the retired codename scan tool) and szl_companion_reason (was the retired codename reason tool). See DEPRECATED.md for the old→new mapping. The old names are not served (they are not registered in tools/list).

    • 6 governance tools — yuyay_gate_check, khipu_append_and_verify, dsse_sign, mesh_quorum_status, puriq_master_tool, governance_pacbayes_bound.
  • Service-derived tools registered dynamically at startup from each backend service's live catalog at /api/<service>/v1/mcp/tools, named <service>_<tool>. The dynamic count is probe-dependent: it equals 37 + (whatever the reachable services publish), and is 0 extra when dynamic registration is disabled or all services are unreachable.

Frontier chain + receipt organism (v8)

Three fixed-endpoint frontier tools (2026-11-15):

  • szl_frontier_chain_read — bounded GET against the fixed public SZLHOLDINGS/frontier-54-runs dataset tree API (path-validated sub-tree, byte budget, canonical digest). Accepts no URL, token, or mutation.
  • szl_battery_score — reads one estate-battery receipt from the same fixed dataset and returns the score AS MEASURED under a typed contract (kind: szl.estate-battery/mass-training, state: MEASURED, string score). A receipt that fails the contract is an honest mismatch, never a guess.
  • szl_holo_cells — pure local deterministic port of the anatomy v4 Λ·HOLO cell math (FNV-1a hash onto the declared trefoil spine; Λ = Conjecture 1 stays a conjecture). No network call: the same chain renders the same organism — the picture is the hash. The port is pinned by a parity test against the deployed v4_holo.js executed under node.

Public GitHub estate evidence

Call szl_github_estate_snapshot with {} to observe the fixed public szl-holdings organization. This is a structural inventory tool, not an LLM answer or a merge bot. It accepts no organization, URL, token, cursor, or other argument. GitHub access uses tokenless, redirect-disabled GETs to a fixed origin; environment credentials and proxies are not inherited by that client.

The observer reports repository identities and default-branch names, bounded open-PR base/head SHAs, draft state, and check runs queried at those exact head SHAs. Citations include request paths and parameters, response byte lengths and SHA-256 digests. A canonical snapshot digest is included in the Khipu receipt and its DSSE payload; a configured P-256 key signs that receipt. Without a key, the envelope remains explicitly PLACEHOLDER with no signatures. A digest or a complete inventory is not an independent witness or a cryptographic signature.

Hard per-call limits: 15 seconds, 20 requests, 3 repository pages (300 records), 50 open PR search results, 100 check runs per PR, 1 MiB of accepted response-body data per response and 4 MiB accepted across the call. Exhaustion stops queued requests and further body acceptance. These are application acceptance limits, not a measurement of wire traffic or transport prefetch; already-delivered but rejected bytes are not counted as accepted. Overflow, timeouts, rate limits, malformed records, stale PR search evidence, and absent or unrecognized check results produce explicit gaps and INCOMPLETE or UNAVAILABLE. Zero checks are UNKNOWN, never success. COMPLETE means the declared observation scope was covered; failed CI may still be completely observed. It does not mean the estate is operational or safe to merge.

This v1 deliberately does not attest private repositories, resolved default branch heads, legacy commit-status contexts, reviews, protection rules, merge eligibility, HF publication, model quality/training, or deployed runtime health. Its multiple requests are not an atomic provider snapshot. Each response is input data, not instructions. Normal Hatun authentication and receipt handling still apply, including optional operator-configured SZL_RECEIPT_SINK forwarding; the GitHub observer performs no provider mutations.

Naming note. The three previously-codenamed backends were purged; their capabilities are now served directly by the live honest a11oy organs on a-11-oy.com: the immune organ (egress policy/gates inspector — Hukulla), the companion organ (operator / reasoning console), and the llm organ (open-LLM tier router). Hatun-MCP addresses them by these honest role names; the live routes are published in /openapi.json.

Recorded reachability snapshot (HONESTY OVER CHECKLIST)

The table below records repository evidence dated 2026-06-16. It is not a current health probe. /healthz and /readyz establish Hatun's local process, receipt chain, and signer only; they do not probe the upstream organs. Before presenting any row as currently LIVE, make a separate bounded, read-only probe of that row's listed route (or a documented non-mutating readiness route), and record the response status, source, and observation timestamp. For POST-only or state-changing surfaces, use a pre-authorized non-mutating contract probe or a timestamped receipt; never trigger an action merely to claim availability. If any required upstream observation is missing, stale, or unusable, present that row as PARTIAL or UNAVAILABLE.

Backend organ Catalog route Recorded state (2026-06-16)
a11oy — llm open-LLM tier router GET /api/a11oy/v1/llm/tiers LIVE (200) — llm_tiers derived from the live tier catalog
killinchu /api/killinchu/v1/mcp/tools LIVE — 4 tools (cue/halt_drone are 2-person)
a11oy — companion operator / reasoning console /api/a11oy/v1/companion/{ask,act,recommend} LIVE (200) — 3 tools derived from live action routes (no JSON /v1/mcp/tools catalog)
a11oy — immune (Hukulla) egress policy inspector GET /api/a11oy/v1/immune/gates LIVE (200, gates-derived) — gates + screen/verdict; the immune screen is the signed /immune/verdict route (there is no separate /screen)
a11oy — command / flagship /api/a11oy/v1/mcp/tools Registers a11oy-flagship tools when the JSON catalog is exposed, else one honest a11oy_status tool. Self-heals on the next server restart once the catalog returns 200 — no code change, no fabricated stubs.

Purge note (2026-06-16). The three previously-codenamed backends were purged (their old routes now 404). Hatun-MCP was repointed to the live honest a11oy twins above and verified 200 before wiring. No tool is ever pointed at a 404; where a sub-route does not exist (e.g. /immune/screen) the tool maps to the closest real route (/immune/verdict) and the mapping is disclosed in the adapter docstring and the catalog reason.

Byzantine quorum + BLS aggregate

szl_lambda_quorum fans a governance-critical Λ verdict out to the five backend services and decides under a Byzantine n ≥ 3f+1 quorum (n=5, f=1): ≥ 4 services must be reachable and ≥ 3 must agree. Participating receipts are BLS12-381 aggregated (py_ecc; honest sha256 Merkle-root fallback if the BLS backend is absent). If any organ's policy route is not live, quorum degrades gracefully (n=4 still satisfies n ≥ 3f+1) and discloses the degradation in governance.quorum.

The BLS keys are held by the gateway process, which signs its observations under per-organ key labels. This is not a collection of independently signed organ attestations. Without HATUN_MCP_BLS_SEED, each aggregator instance uses a random ephemeral seed; its identity changes on restart. Responses include ordered public_keys, key_source, and ephemeral so consumers can distinguish signature verification from trusted identity. Pin or authenticate the public keys separately before relying on origin claims. For a persistent identity, supply a private, high-entropy seed through the secret store; never use the retired public default hatun-mcp-doctrine-v11 as a configured secret. Receipts made with that historical default cannot establish an exclusive signer identity.


Run locally (stdio)

pip install -r requirements.txt
python -m hatun_mcp.server          # stdio mode for Claude Desktop / Codex

Run hosted (Streamable HTTP)

uvicorn hatun_mcp.server_http:app --host 0.0.0.0 --port 7860
# MCP endpoint:  http://127.0.0.1:7860/mcp/   (stateless Streamable HTTP)
# Process liveness: http://127.0.0.1:7860/healthz
# Signed-release and operator-binding readiness: http://127.0.0.1:7860/readyz

Configure an existing admitted operator key using the explicit scope binding in HTTP operator admission. HTTP exposes only the three documented read capabilities and the locked-doctrine resource; the full local package catalog is not HTTP permission. Legacy SSE and message endpoints are disabled: admitted requests to /sse or /messages return 410, and discovery reports sse_endpoint: null. Use /mcp/ for hosted clients.

The DSSE signing key is injected at runtime via the HATUN_MCP_SIGNING_KEY (PEM) operator-managed secret; without it the signer runs in honest PLACEHOLDER mode (clearly labeled, never a fake signature).

/healthz proves that the process and local receipt chain can answer. /readyz is the fail-closed investor/deployment contract: it returns 200 only when the receipt chain verifies, a non-placeholder signing key is active, and an explicit operator scope binding is configured; otherwise it returns 503 with the failing check named. The public server card advertises only the schemes this process accepts: apiKey, plus x402 when payment admission is on.

Optional x402 payment admission lets a request that Cloudflare Monetization Gateway charged use the same read-only HTTP profile. Hatun verifies the gateway's Ed25519 PAYMENT-CONTEXT JWT against the pinned JWKS and refuses the request if the keys cannot be fetched (fail closed). For upto it reports PAYMENT-SETTLEMENT. It is off unless HATUN_MCP_X402_SCHEME is set. The settings, admission rules, settlement behaviour and proof boundary are in HTTP operator admission.

MCP manifest attestation

GET /.well-known/mcp-manifest-attestation returns a cached integrity binding for the exact raw bytes served by GET /.well-known/mcp (all server-card aliases serve those same bytes). It contains a deterministic https://in-toto.io/Statement/v1 with SHA-256 subject digest and the custom predicate type https://szlholdings.com/attestations/mcp-manifest/v1. When the existing P-256 signing key is configured, the statement is carried in a real DSSE envelope whose payloadType is application/vnd.in-toto+json. Without that key, the response is explicitly signing.state=UNSIGNED with dsseEnvelope=null; an empty signature is never presented as signed.

The artifact is built once at process start and accepts no caller-supplied signing payload. It does not mint a Khipu receipt. Its scope is byte integrity only: it does not attest runtime tool parity, upstream availability, or the behavior behind the card. The MCP server card and this well-known route are an SZL DRAFT extension, not a claim of a ratified MCP discovery standard. keyid is only a hint; verifiers must establish trust in the P-256 public key out of band (the same-origin /pubkey route is not an independent trust anchor). Transparency-log inclusion remains explicitly unavailable.

Evaluate the hosted contract

curl -i http://127.0.0.1:7860/healthz
curl -i http://127.0.0.1:7860/readyz
curl -s http://127.0.0.1:7860/api/console-state

/api/console-state (hatun_mcp/state.py) is the read behind the human console at /. The commands above target your locally started server. For a deployment, use its admitted operator-provided origin, not the retired standalone Space host. It is assembled in-request from this process only: the tool catalogue is enumerated from the LIVE FastMCP registry (not a hand-maintained list), the receipt depth and head hash come from the live Khipu chain, and card_parity reports a MEASURED comparison between the published server card and that runtime registry. Anything it cannot read is returned with an honest label (UNAVAILABLE) and no number — there is no seeded snapshot, so the console shows UNAVAILABLE rather than a stale value when a reading fails. It mints no receipt and attests nothing beyond the reading itself.

Record the response status and observation time. Report healthz=200 as Hatun process liveness only. Report readyz=200 as Hatun's repository-defined local receipt-chain and signer readiness only. These checks do not establish killinchu or a11oy organ availability. Before labeling any upstream row LIVE, separately run a bounded, read-only probe of its listed route (or a documented non-mutating readiness route) and record the route, response status, source, and observation timestamp. For POST-only or state-changing surfaces, require a pre-authorized non-mutating contract probe or timestamped receipt instead of triggering an action. If Hatun is ready but an upstream observation is missing, stale, or unusable, report that row as PARTIAL or UNAVAILABLE. Never fall back to the sample client configuration.


MCP client setup

Claude Desktop

The snippets below are SAMPLE local-server configurations. Start the HTTP server first, configure an accepted API key, and replace szl_YOUR_KEY. For a remote deployment, substitute the admitted operator-provided HTTPS MCP URL. Drop examples/claude-desktop-config.json into ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows), replacing szl_YOUR_KEY:

{
  "mcpServers": {
    "hatun-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote",
        "http://127.0.0.1:7860/mcp/",
        "--header", "Authorization: Bearer szl_YOUR_KEY"]
    }
  }
}

Codex (~/.codex/config.toml)

[mcp_servers.hatun-mcp]
command = "npx"
args = ["-y", "mcp-remote", "http://127.0.0.1:7860/mcp/",
        "--header", "Authorization: Bearer szl_YOUR_KEY"]

Continue (~/.continue/config.json)

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "mcp-remote",
            "http://127.0.0.1:7860/mcp/",
            "--header", "Authorization: Bearer szl_YOUR_KEY"]
        }
      }
    ]
  }
}

Tests

HATUN_MCP_DISABLE_DYNAMIC=true python -m pytest tests/ -q
# tests/test_server.py    — list tools, call a tool, assert response shape
# tests/test_github_estate_snapshot.py — bounded public GitHub observer, mocked provider
# tests/test_quorum.py    — quorum math + threshold edge cases + BLS aggregate
# tests/test_adapters.py  — mocked organ endpoints, adapter wiring + honest gaps
# tests/test_governance.py— Khipu chain, Yuyay gate, PURIQ factor (pre-existing)
# tests/test_http_routes.py — exact-byte card attestation + public HTTP contracts
# tests/test_payment_context.py — PAYMENT-CONTEXT verifier, pinned JWKS cache, fail-closed outage
# tests/test_http_payment_admission.py — x402 admission, refusals and upto settlement over real MCP

The server tests also import the estate regression class so the existing explicit-file hosted CI gate exercises it. They verify real in-memory MCP discovery/calls, argument rejection, canonical digest binding, and an ephemeral P-256 signature. Provider responses in these tests are SIMULATED; passing them does not publish the new tool or establish current GitHub/HF health.

python tests/proof_inmemory.py exercises the real in-memory MCP protocol and checks exact static runtime/server-card name parity. The proof disables dynamic catalog probing and receipt-sink forwarding in its own process. CI also runs it from an unrelated working directory to verify the documented direct command.

The Ouroboros loop (doctrine cross-reference)

hatun-mcp does not implement the estate's Ouroboros bounded-recursion kernel itself; its PURIQ orchestrator is a bounded, single-pass per-tool-call flow, not recursion. This section is a doctrine cross-reference plus an honest note on how that flow embodies the loop's receipt-closed identity (receipts.in ≡ receipts.out, already carried in this README).

The canonical definition is the receipt-closed kernel szl-holdings/ouroboros → src/loop-kernel.ts (runLoop): bounded recursion with measurable convergence that MUST terminate on one of four exit conditions — converged | consistent | aborted | budgetExhausted — and emits a governance receipt for every run. The trace is the product.

How hatun-mcp embodies that primitive (in hatun_mcp/puriq.py):

  • Bounded & terminating. Each tool call is a finite pipeline — Yuyay-13 gate → mesh quorum (Byzantine n ≥ 3f+1) → HUKLLA tripwire → Khipu append → DSSE-sign → compose the master-formula scalar — that always terminates within a latency budget and returns a receipt hash. There is no unbounded loop.
  • Receipt-closed. Every call mints a Khipu link on an append-only sha256 DAG and the client receives the receipt hash. That is this repo's live realization of the header identity receipts.in ≡ receipts.out — a metaphor (doctrine, not math), where each signed receipt is fed back into the DAG as an auditable input.

Honesty (Doctrine v11 · 749/14/163): Λ is consumed here as an input scalar in [0,1] and is Conjecture 1 — advisory, never a proven theorem. This is a bounded, terminating governance flow — it makes no perpetual-motion or zero-cost claim.


Doctrine v11 LOCKED — 749 / 14 / 163 · Λ = Conjecture 1 (NOT a theorem) · SLSA L1 honest · L2 verified-provenance on roadmap (L3 not claimed) receipts.in ≡ receipts.out

Signed-off-by: Yachay <yachay@szlholdings.ai> Co-Authored-By: Perplexity Computer Agent <agent@perplexity.ai>

Estate on Hugging Face: models, datasets and Spaces are published under the SZLHOLDINGS org.

Metadata

Release files for hatun-mcp 1.0.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hatun-mcp 1.0.4
File Size Uploaded Provenance Actions
hatun_mcp-1.0.4.tar.gz 219.8 kB With provenance Details for hatun_mcp-1.0.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hatun-mcp 1.0.4
File Interpreter ABI Platform Actions
hatun_mcp-1.0.4-py3-none-any.whl Python 3 none any Details for hatun_mcp-1.0.4-py3-none-any.whl

Total release size: 370.3 kB

Release files / hatun_mcp-1.0.4.tar.gz

Download URL hatun_mcp-1.0.4.tar.gz
Size 219.8 kB
Tags Source
SHA-256 checksum
How to use checksums
c399e95db29d2a3e08f0a8834e6cc69e9bcde8b36dc60ad9fae2640a9d65f2f3
BLAKE2b-256 checksum
How to use checksums
bcb069a1eacf83feca889894f9c558acb42ed665f1ef00c591b15a9a55846eb7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / hatun_mcp-1.0.4-py3-none-any.whl

Download URL hatun_mcp-1.0.4-py3-none-any.whl
Size 150.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3f720a3c70d89d67a8e59ca63592903983de48b0a2791655b3a2b7815f6dd97d
BLAKE2b-256 checksum
How to use checksums
5007eff3e2e171376696fd812080da18db205fe92bb32786d58d83c1701c1f1d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for hatun-mcp 1.0.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for hatun_mcp-1.0.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.4 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page