# MCP server

`ccc-statusd` is the local daemon every seat on a UCC machine talks to. Besides messaging and lifecycle, it serves a **Model Context Protocol (MCP) server** over HTTP on `localhost`. Through it your agent reads, writes and queries the fleet's markdown records — session cards, task boards, memos, wiki pages — with the guards other agents rely on, instead of editing files raw. When a skill says `read`, `put` or `sql`, it means these tools.

```mermaid
flowchart LR
  H[Claude Code seat] -- "HTTP + token" --> D[ccc-statusd<br/>MCP server]
  D -- "~/MERIDIAN.md" --> R1[(sessions root<br/>primary)]
  D --> R2[(home-wiki)]
  D --> R3[(other roots)]
```

## The tools

Eleven tools, one surface. The harness lists them as `mcp__ccc-statusd__<name>`.

| Tool | One line |
|---|---|
| `read` | A record as its section map (toc) or as the sections you name. First call on any record. |
| `put` | One guarded write: section edits, a frontmatter patch, an attestation pin. Receipt's first word is the verdict (`wrote`, `born`, `unchanged`, `skipped`, `partial`). |
| `sql` | DuckDB over one root's corpus — docs, sections, links, tags, tasks. Board and seat questions. |
| `script` | A Starlark read-decide-write program, landed as one sealed commit. |
| `run` | Runs a page's declared `task.<name>` blocks. |
| `sub` | What changed under the primary sessions root since a cursor. |
| `roots` | The bound trees, the primary, and build/daemon/engine freshness. Your orientation call. |
| `resolve` | Where a ref lands — physical path, addressing kind, root — without reading it. |
| `walk` | The pin graph up (what a record rests on) or down (who rests on it). |
| `token_count` | Real token cost of a text, record or section, through a live tokenizer. |
| `worktree` | `op: enter` opens a branch and git worktree in your work folder; `op: exit` releases it. The one worktree door. |

Parameter semantics, refusal vocabulary and the loops are the installed **ccc-meridian** skill (`load /ccc-meridian`; full detail in its `references/mcp-tools.md`). The records themselves — cards, rosters, memos, the armed rules that fill and refuse them — are the [Meridian tools](#what-you-have/chapter.meridian-tools) chapter and [Sessions & wiki](#sessions-wiki). The authority on which tools exist is the live server: a `roots` call, or your harness's own tool list.

## Roots and the `sessions:` alias

The daemon does not see your whole disk. It sees the **mount table** in `~/MERIDIAN.md` — one `meridian-mount` block per root, each with a `name:` and a `path:`. One mount is `primary: true` and carries `alias: sessions`; that is the sessions root, the tree the daemon writes and `sub` watches. A mount carries at most one alias.

Ref grammar for every tool is `[root:]path`:

- `sessions:agents/<short-id>/<short-id>.md` — root-qualified, reaches the named tree.
- `tasks/fix-auth.md` — a bare path is **ambient**: it lands in your own session directory.
- An absolute path works when it falls under a bound root.
- A `#` fragment refuses; sections are addressed by the `sections`, `at` or `hpath` parameters.

`roots` shows the table as the daemon parsed it; `resolve` says where one ref would land before you write there. The `mrd` CLI (`mrd read`, `mrd config get`) is the other client of the same engine and reads the same table.

## How your seat gets it

Three pieces, all installer-owned; you do not hand-edit an `.mcp.json`.

1. **The server file** — `$UCC_HOME/config/mcp/ccc-statusd.md`. Frontmatter gates it (`requires: ["exec:${HOME}/.local/bin/ccc-statusd", "env:CCC_STATUSD_MCP_TOKEN"]`); the body's JSON fence is the server object: type `http`, url `http://localhost:${CCC_STATUSD_MCP_PORT:-19223}/mcp`, an `Authorization: Bearer` header.
2. **The launch page opts in by name** — `mcpServers: [ccc-statusd, shellkit]` in `$UCC_HOME/config/launch/default.md`. A launch page without that line starts a seat with no record tools.
3. **The token** — `$UCC_HOME/default-env.sh` exports `CCC_STATUSD_MCP_PORT` (default `19223`) and `CCC_STATUSD_MCP_TOKEN`, reading the token the daemon minted at `$UCC_HOME/cache/ccc-status/mcp-token` when the variable is unset.

The hazard, in the server file's own words: a launcher whose shell lacks the token "launches an agent with no read/put/sql/sub at all, silently." So the first thing to do in a new seat is call `roots`. If it answers with the mount table, you are wired. From a shell, `curl -s -o /dev/null -w '%{http_code}\n' http://localhost:19223/mcp` printing `401` means the daemon is listening and wants the bearer token; a connection refused means the daemon is not running (`ccc-statusd status`).

## Which harnesses have it

- **Claude Code seats — yes.** Every UCC launcher that runs the Claude Code harness gets the server, including a gateway profile that points Claude Code at a non-Anthropic model. This is the path to full fleet participation: cards, boards, memos, AskUserQuestion.
- **A native Codex CLI seat — no.** It has no ccc-statusd MCP. It can read records with `mrd read`, and the hooks plane still works (its card and daemon row exist), but it cannot `put`, write a board, or answer an AskUserQuestion. Details and the workaround are on [Codex (limited)](#codex).

## Names you will meet

- `sessions:` — the primary root's alias; every skill spells it.
- `~/MERIDIAN.md` — the mount table and this machine's `mrd config` values.
- `mcp__ccc-statusd__read` and friends — the tools as the harness names them.
- `CCC_STATUSD_MCP_PORT`, `CCC_STATUSD_MCP_TOKEN` — the gate.
- `ccc-meridian` — the skill that carries the tools' semantics.