sagrada-mcp

Model Context Protocol (MCP) server for Sagrada — track and verify reasoning state for AI systems, and read attested repo-history records.

Sagrada gives Claude Code (and any MCP-capable client) durable, content-addressed memory of design decisions, claim revisions, contradictions, and the cryptographically verifiable chain of edits that produced the current knowledge state.

What this repository is

The source of the sagrada-mcp package on PyPI, so you can read what you installed instead of taking our word for it.

The repo was created after 0.3.0 shipped. Its first commit is that release's source, verbatim, tagged v0.3.0 — so the code you install and the code you read can be checked against each other:

pip download sagrada-mcp==0.3.0 --no-binary :all: --no-deps -d /tmp/pypi
tar xzf /tmp/pypi/sagrada_mcp-0.3.0.tar.gz -C /tmp
mkdir -p /tmp/tagged && git archive v0.3.0 | tar x -C /tmp/tagged
diff -r /tmp/tagged /tmp/sagrada_mcp-0.3.0 --exclude PKG-INFO   # no output

CI runs that diff on every push. main is ahead of v0.3.0 and carries unreleased work; pip install sagrada-mcp gives you the tag, not the branch.

What is not here: the compiled sagrada engine (Rust), which the 12 reasoning-tracker tools need. It installs from PyPI as sagrada-engine, and its source is not published. The preflight gate — the part that refuses — is in this repo, is pure Python, and does not depend on the engine.

Installation

Mode 1: pip install (clean venv, no repo checkout)

pip install sagrada-mcp

This installs the server plus vendored copies of its not-yet-published dependencies (see _vendor/README.md). One server, 21 tools:

• The 3 preflight-gate tools (preflight_action, list_beliefs, verify_receipt) gate consequential tool calls against the repo's typed beliefs and emit Ed25519-signed action receipts to .sagrada/receipts.jsonl, each independently verifiable offline with uvx er1-verify (1.0.1 or later — an unpinned install against a version constraint is a declared coverage gap the verifier recomputes, a receipt shape 1.0.0 predated). Deterministic and engine-free — refusal does not depend on the binary wheel.

  Receipts are signed with a keypair created for your repo on first use: the private half lives at .sagrada/operator_key (mode 0600 on POSIX, gitignored, never leaving your machine), the public half at .sagrada/operator_key.pub is meant to be committed. verify_receipt checks a receipt's signer against that committed key and the signed succession chain behind it, so a receipt from a key that was never this repo's comes back foreign rather than passing quietly. Earlier versions minted a key per process, which made every signature unpinnable — "signed by X" where X existed for one run.

  What that establishes is continuity, not identity: if you pinned this repo's fingerprint out of band, and the private key has never left the machine, then a swap of the signing key shows up. Each clause matters — a signature proves possession of a file, and files copy.

  For Claude Code there is also an ENFORCED layer: the sagrada-preflight-hook console script can be wired as a PreToolUse hook, and then blocks HALTed calls in-band. Installing the package does not register it — nothing here edits your Claude settings. You add it yourself; preflight_hook.py carries the exact one-line entry to paste.

• The 6 repo-record (crux) tools are fully functional given a .crux artifact (SAGRADA_CRUX). Without one they return a helpful error string.

• The 12 reasoning-tracker tools additionally need the compiled sagrada-engine wheel (a hard dependency as of 0.3.0; installed automatically on platforms with wheels). If the engine is somehow absent they return a clear JSON error naming the missing piece — never a traceback.

Mode 2: from a clone of this repo

git clone https://github.com/Cruxia-Labs/sagrada-mcp && cd sagrada-mcp
pip install -e ".[dev]"
pytest -q

To run the server itself, note that it speaks MCP over stdio and does not exit — it waits for a client, so run it from your MCP client's config rather than expecting a prompt back:

python -m sagrada_mcp.server     # blocks; Ctrl-C to stop

The server prefers the real sagrada_tracker / sagrada_preflight packages when they are importable and falls back to the copies in sagrada_mcp/_vendor/ otherwise — so it behaves identically here and in the upstream tree those copies come from. In a clone the vendored copies are what runs, and the test suite binds the same ones the server did (tests/conftest.py prints which, in the pytest header).

Configure in Claude Code / Claude Desktop

{
  "mcpServers": {
    "sagrada": {
      "command": "sagrada-mcp",
      "env": { "SAGRADA_PROJECT": "/path/to/your/project" }
    }
  }
}

(In a repo checkout use "command": "python", "args": ["-m", "sagrada_mcp.server"].)

Tools provided (21)

Preflight gate (3) — deterministic, no engine required

Recognition is a finite, best-effort vocabulary. The gate maps a tool call to beliefs by reading the forms an agent actually emits — imports, package-manager installs, deploy targets, env assignments. An action expressed in a form it does not recognise is not mapped, and an unmapped action does not conflict with anything, so it is ALLOWed. Treat HALT as an enforced policy check on recognised actions, not as containment.

Reasoning tracker (12) — require the compiled sagrada engine

Repo-record / crux (6) — work anywhere, given a .crux artifact

Deterministic reads of a transformed repo-history record — no model, no network, no clock. Every answer carries the record reference (artifact, state_root, receipt) for offline verification.

There is no public builder for .crux artifacts yet. The reader is here and is stdlib-only, so these six tools work fully against an artifact you already have — but the tool that builds one is not in this repo and is not published. If you have no artifact, each crux tool returns a pointer rather than failing, and until a builder ships that pointer is the honest end of the road for a public user.

Resources provided (3)

Environment variables

License

Apache-2.0. Published by Cruxia-Labs.