> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mzizi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# The MCP server

> mcp.mzizi.dev: the registry, tokens, doctrine and skills from bundled files, plus the docs as federated docs_* tools. Free with no sign-in, except the Fundi tools.

The Mzizi MCP server gives agents the registry, the brand tokens, the architecture model,
the doctrine, the agent skills and these docs over the
[Model Context Protocol](https://modelcontextprotocol.io). It is the `mzizi-mcp` Cloudflare
Worker, published as [`@nyuchi/mzizi-mcp`](https://www.npmjs.com/package/@nyuchi/mzizi-mcp)
(`0.11.2`, read from npm on 30 September 2026; the hosted server answered `initialize` with
the same version, and the MCP Registry lists it). In the
[MCP Registry](https://registry.modelcontextprotocol.io) it is
`io.github.mzizi-dev/mzizi-mcp`, listing both the hosted endpoint and the npm package. The
earlier entry under the nyuchi namespace is deleted.

## Connecting

```json theme={null}
{
  "mcpServers": {
    "mzizi": {
      "type": "http",
      "url": "https://mcp.mzizi.dev/mcp"
    }
  }
}
```

Streamable HTTP. `mzizi.dev/mcp` answers `308` to this endpoint, so old clients keep
working, but point new ones here directly.

To run it locally over stdio, with no network for anything but the docs tools:

```json theme={null}
{
  "mcpServers": {
    "mzizi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@nyuchi/mzizi-mcp"]
    }
  }
}
```

The stdio build takes no environment and holds no credential. The registry data and skills
ship inside the package.

## Who can use it

The MCP server is free, with no gate, as the owner decided on 29 September 2026. Every tool
except the Fundi tools is served without sign-in. On 30 September 2026 an anonymous
`initialize` and `tools/list` on `https://mcp.mzizi.dev/mcp` returned all fourteen tools, and
an anonymous call to `mzizi_search` returned results.

| Tools | Sign-in |
| - | - |
| Every `mzizi_*` read tool, every `docs_*` tool | **None.** Free |
| `mzizi_fundi`, `mzizi_report_issue` | A signed-in console user, through WorkOS OAuth |

The Fundi tools stay gated because they tie into the console at `app.mzizi.dev`:
`mzizi_report_issue` files into the Fundi issue desk, and `mzizi_fundi` delegates work to
Fundi on a user's behalf. Both need to know who the user is. The server advertises its OAuth
metadata at
[`/.well-known/oauth-protected-resource`](https://mcp.mzizi.dev/.well-known/oauth-protected-resource),
so MCP clients can run the sign-in flow for those tools themselves. Called without sign-in,
a Fundi tool answers with how to sign in rather than failing silently. A client that cannot
run the flow can connect to `https://mcp.mzizi.dev/mcp/signin` instead, which asks you to sign
in and then serves every tool.

Anonymous requests are rate-limited to 120 per 60 seconds per IP address, according to the
server's `catalogue.json`. Signed-in requests are not.

## Discovering the tools

**Ask the server, not a page.** A list written down anywhere, this one included, is only as
fresh as its last edit.

* `tools/list` over MCP is the live answer.
* [`https://mcp.mzizi.dev/catalogue.json`](https://mcp.mzizi.dev/catalogue.json) is the same
  list over plain HTTP, with no sign-in, including which older tools each one replaces.
* The `mzizi_mcp_describe` tool, and the `mzizi://tools` resource, describe the tools and
  the data sources.

On 30 September 2026, `catalogue.json` and an anonymous `tools/list` both listed fourteen
tools:

| Tool | What it answers |
| - | - |
| `mzizi_search` | Word search over components, conventions, AI instruction sets and releases |
| `mzizi_get_component` | One component in full, Rust first; optional docs and version history |
| `mzizi_list_components` | The paged index, filterable by node, owner, collection, type and `rust` |
| `mzizi_get_tokens` | The brand system, including all 21 colour families |
| `mzizi_get_architecture` | The DNA helix, or one node or rung |
| `mzizi_get_doctrine` | Ubuntu pillars and principles, conventions, AI instruction sets |
| `mzizi_get_skills` | The five agent skills, listed or one in full |
| `mzizi_check_accessibility` | Contrast against the Mzizi floor, computed locally |
| `mzizi_report_issue` | Files into the Fundi issue desk. **Gated** |
| `mzizi_fundi` | Delegates a run to Fundi. **Gated** |
| `mzizi_mcp_describe` | This server's tools, what each replaces, and its data sources |
| `docs_search_mzizi` | Search these docs (federated) |
| `docs_query_docs_filesystem_mzizi` | Read-only `rg`, `cat` and `tree` over these docs' pages (federated) |
| `docs_submit_feedback` | Report a problem with these docs (federated) |

Start with `mzizi_search` when you do not know the name of the thing you want, and
`mzizi_get_component` when you do.

## Components, Rust first

From `0.11.0` the component tools lead with [Mzizi Roots](/roots/overview), the Rust
implementation, wherever one exists. The React (TSX) components are the React build: they
keep working, but they are deprioritised and come second.

`mzizi_get_component` takes `name` (a former `nyuchi-*` name resolves to its `mzizi-*`
successor) and an optional `include` of `"docs"`, `"versions"` or both. It answers with these
fields, in this order:

| Field | What it holds |
| - | - |
| `name` | The component's current name |
| `renamedFrom` | The name you asked for, when it was a former name. Absent otherwise |
| `lead` | `"rust"` when the component has a Rust implementation, otherwise `"react"` |
| `note` | Which build to use, in words |
| `rust` | The Roots implementation, or `null` when there is none |
| `react` | The React build: `build: "react"`, `status: "deprioritised"`, an `install` line, then the registry's `/v1/ui/{name}` body |
| `docs` | With `include: ["docs"]`: use cases, variants and accessibility |
| `versions` | With `include: ["versions"]`: version history, from the registry's changelog |

`rust` is the registry's `GET /v1/rs/{name}` answer, with the install before the source:

* `crate`: `{ name, registry, git }`, the crate the component ships in, such as `mzizi-brand`;
* `install.cargo`: `cargo add <crate>`, the crates.io release;
* `install.pinned`: the same `cargo add` with `--git` and `--rev` at the server's registry
  pin, which builds exactly the source shown;
* `module`: the crate's Rust path, such as `mzizi_brand`;
* `contract`: the component's `contract … end` block, or `null` when its source declares none;
* `files`: the `.rs` source, inline.

`react.install` is `npx shadcn@latest add https://api.mzizi.dev/v1/ui/<name>`. If the registry
refuses the React build but Rust exists, `react` is `{ build, error }` and the Rust still leads.

<Warning>
  **Breaking for readers of `0.10.x`:** the React body moved from `component` to `react`, and
  `renamedFrom` moved to the top level.
</Warning>

`mzizi_list_components` rows carry `rustCrate` when the component has Rust, the response
carries `withRust` (how many of `total` have it), and `rust: true` or `rust: false` filters on
it. On 30 September 2026, `rust: true` listed 55 of the registry's 577 components.
`mzizi_search` component hits carry `rustCrate` the same way, and at an equal score a
component with Rust ranks first; a better word match still wins.

## Where its data comes from

**Nothing is read from a database, and no registry data is fetched at request time.**

| Data | Source | How it gets in |
| - | - | - |
| Components, docs, tokens, the helix, doctrine, conventions, changelog, renames | [`mzizi-dev/mzizi-registry`](https://github.com/mzizi-dev/mzizi-registry) at a pinned commit | Generated at build time by running the registry's API handlers, then bundled |
| Agent skills | The `@nyuchi/mzizi-skills` bundle | Generated at build time and bundled |
| Documentation | The Mintlify MCP at `https://docs.mzizi.dev/mcp` | Federated live as `docs_*` tools |

Because the generator runs the registry's API handlers rather than re-deriving their output,
a tool answers with the payload `api.mzizi.dev/v1` would give at the same commit. The registry
no longer carries those handlers: it removed its Next.js app, `app/api/v1/**` included, on
2 October 2026 (mzizi-registry #389 and #391). `mzizi-mcp` keeps the eleven it calls in
`mzizi-mcp/scripts/registry-handlers/`, ported unchanged from registry commit `270af9f`, the
last with them (agent-tools #172). They run at build time only and are not part of the
Worker's bundle. They still read through the registry's own `lib/` modules, which resolve into
the checkout at the pinned commit, so the data is that commit's. The generator replaces every
npm import those handlers make with a module that throws when used (`next/server` gets a small
response shim instead), so a handler that reaches for a database or a service fails the build
rather than shipping an empty answer.
`catalogue.json` names the pinned registry commit in `source.registry`, and
`mzizi_mcp_describe` reports it. Read the live pin there rather than from this page, and
compare it with the pin [`api.mzizi.dev`](/platform/api-gateway) reports in its
`X-Mzizi-Source` header. The two are meant to be the same commit, but they move separately, so
they can differ for a while after one of them moves. For example, `0.11.2` moved the pin by
hand on 30 September 2026 to registry commit `e1c1c89`, which was then also the API's; that is
an example, not the current value. Moving to newer registry content is a change to that pin,
made in a pull request that CI checks.

The pin, `ref` in `mzizi-mcp/registry.pin.json`, has the same bot as
[the API gateway's](/platform/api-gateway#how-the-pin-moves). Every hour it compares the pin
with registry `main` and keeps one pull request, from the branch `bot/registry-pin`, that
moves it. That pull request merges itself (rebase) only when every check on it is green, and
otherwise waits for review. The bot is live on the `RELEASE_BUMP_TOKEN` secret (it opened
agent-tools #169 on 2 October 2026), and a bump by hand still works.

The server holds no database credential. Former `nyuchi-*` component names resolve to their
`mzizi-*` names through the registry's rename map, bundled with the rest.

### The skills

`mzizi_get_skills` serves the five skills of [`@nyuchi/mzizi-skills`](/toolchain/skills),
bundled from the skills' source when the server is built, so it answers with the same version
as npm. From `0.11.1`, each skill's `source` names where it is authored,
`mzizi-dev/agent-tools/mzizi-skills/skills/<name>`. The skills renamed or removed in `0.8.0`
have no aliases; see [renamed and removed skills](/toolchain/skills#renamed-and-removed-skills).

### The docs tools

These docs run their own MCP server, which Mintlify hosts at `https://docs.mzizi.dev/mcp`.
It is public and needs no sign-in. The Mzizi MCP server lists its tools under a `docs_`
prefix and forwards each call unchanged:

* it caches the upstream tool list for five minutes;
* if a refresh fails it reuses the last good list, and with nothing cached it falls back to
  a built-in snapshot of the upstream definitions;
* a failed call comes back as a tool error naming the docs server and the reason.

The `docs_*` names mirror whatever `docs.mzizi.dev/mcp` lists, so they can change when these
docs change. You can also connect to `https://docs.mzizi.dev/mcp` directly.

## The Fundi tools

Fundi is the self-healing agent behind the console, run under Nyuchi. Two tools reach it.

**`mzizi_report_issue`** reproduces and drafts an issue, then logs it to Fundi's issue desk.
Fundi files the GitHub issue with its healing plan, and records the issue's lifecycle, which
is how the desk and the console can tell you whether your report was picked up.

**`mzizi_fundi`** delegates long runs, such as a security, chaos or accessibility run, to
Fundi over the Agent2Agent (A2A) protocol. A run is a **task** with a lifecycle, not a
blocking tool call: you submit it and get a task id back at once, then poll its status or
cancel it. It replaces the older `fundi_status`, `fundi_submit_test`, `fundi_task_status`
and `fundi_cancel_task` tools.

<Note>
  The A2A bridge is built through its second stage: the agent card, task submission, status
  and cancellation. The runs behind it, streaming updates and push notifications are still
  design. A submitted task can come back parked as accepted but not executed.
</Note>

Both tools act for a real, signed-in console user. The server never hands a machine
credential to a client or to the CLI.

## Use cases

### Building against the registry

1. `mzizi_list_components`, filtered to the node you are building at.
2. `mzizi_get_component` for the full document of anything that looks right. Where a Rust
   implementation exists, it leads: depend on the crate in `rust.install` (see
   [Mzizi Roots](/roots/overview)). `mzizi_list_components` with `rust: true` lists only those.
3. Install it (see [consuming the registry](/registry/consuming)).

### Reviewing a change

1. `mzizi_get_tokens` to check a component uses published tokens, not raw values.
2. `mzizi_get_architecture` to check it sits where its imports say it does.
3. `mzizi_check_accessibility` for contrast on any new colour pairing.

### Answering a question about Mzizi

`docs_search_mzizi`, then `docs_query_docs_filesystem_mzizi` to read the page it found.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.