hatun-mcp

---
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 signed governance receipts
---

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Doctrine v11 LOCKED](https://img.shields.io/badge/Doctrine-v11_LOCKED-d4a444.svg)](https://github.com/szl-holdings/lutar-lean)
[![CI](https://github.com/szl-holdings/hatun-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/szl-holdings/hatun-mcp/actions/workflows/ci.yml)
[![SLSA](https://img.shields.io/badge/SLSA-L1_honest_%C2%B7_L2_roadmap-22c55e.svg)](https://slsa.dev/spec/v1.0/levels)

<div align="center">

# 🪢 hatun-mcp

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

The **one signed 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.

[Hatun Gateway](https://a-11-oy.com/wires) ·
[GitHub Org](https://github.com/szl-holdings) ·
[LLM Router](https://github.com/szl-holdings/szl-router)

</div>

> **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](https://a-11-oy.com/wires), which is not
> itself proof that this package's `/mcp/` endpoint or a newly added tool is deployed.
> See the [surface contract](docs/HATUN_SURFACE_CONTRACT.md). The monorepo copy at
> [`platform/packages/hatun-mcp`](https://github.com/szl-holdings/platform/tree/main/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.

<div align="center">

`receipts.in ≡ receipts.out`

</div>

---

## What this is

A **real, operational** Model Context Protocol server built on the official `mcp`
Python SDK (`mcp.server.fastmcp.FastMCP`). Every tool call is governed by the PURIQ
formula:

1. **Authenticate** the client (SZL API key → `client_id`); 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](#run-locally-stdio), then inspect `tools/list` | Local startup proves only the local process; backend reachability is separate |
| **Integrator** | [MCP client setup](#mcp-client-setup) | The checked-in client configuration is **SAMPLE** and does not include credentials |
| **Evaluator** | [Hosted health contracts](#evaluate-the-hosted-contract), then [Tests](#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

- **26 static tools** registered at import (verifiable: `tools/list` returns 26 with
  `HATUN_MCP_DISABLE_DYNAMIC=true`):
  - **20 `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_formula_evaluate`, `szl_github_estate_snapshot`, `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).
    > 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`](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 26 + (whatever the reachable services
  publish), and is 0 extra when dynamic registration is disabled or all services are
  unreachable.

### 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 —