Clef Mcp

Quick start

# 1. Detect hardware, download the model (~6 GB) + llama.cpp runtime, verify checksum + inferencenpx clef-mcp install
# 2. Register the MCP server + agent skill in your clients (zcode, claude-code, codex, cursor)npx clef-mcp setup
# 3. Run the MCP server (stdio)npx clef-mcp

clef-mcp (step 3) never downloads anything. If the model is missing, tool calls return a structured MODEL_NOT_INSTALLED error with a hint. Steps 1 and 2 combine: npx clef-mcp install --setup.

Why not just ask the LLM?

Sweet spot: decision points inside agent loops — next action, routing, classification, severity, yes/no judgment — asked dozens of times per task.

The clef_decide tool

{  "state": {    "task": "Fix failing tests",    "error": "TypeError: Cannot read properties of undefined"  },  "questions": {    "next_action": {      "type": "choice",      "instructions": "What should the coding agent do next?",      "criteria": {        "inspect": "Inspect the code and gather more information",        "modify": "Modify the code",        "test": "Run additional tests",        "ask_user": "Ask the user for clarification"      }    },    "confidence": {      "type": "score",      "instructions": "How confident are you in this decision?",      "criteria": ["very_low", "low", "medium", "high", "very_high"]    },    "is_outage": { "type": "noul", "instructions": "Is a service down?" }  }}

Response — strictly structured, never prose:

{  "model": "clef-flash",  "decisions": {    "next_action": { "answer": { "inspect": 0.72, "modify": 0.12, "test": 0.14, "ask_user": 0.02 } },    "confidence":  { "answer": { "very_low": 0.01, "low": 0.04, "medium": 0.18, "high": 0.61, "very_high": 0.16 } },    "is_outage":   { "answer": { "true": 0.9, "false": 0.1 } }  }}

Batch up to 64 questions per call — they are scored in one forward pass. state is treated strictly as data: never executed, never interpreted as instructions for the server.

Prompts & resources

The server ships four MCP prompts (canned, decision-shaped asks — your client lists them via prompts/list):

And three resources (read-only, no model needed):

Measured, not marketed

Apple M4 Pro, Clef-Flash Q4_K_M (6 GB), single request through the full MCP stdio path:

Quality gate: a 30-case evaluation dataset (coding / security / classification / routing / yes-no) — 86.7% pass on the live model. Run it yourself: clef-mcp evals.

Register with your MCP client

claude mcp add clef-mcp -- clef-mcp# or, without a global install:claude mcp add clef-mcp -- npx -y clef-mcp

[mcp_servers.clef-mcp]command = "clef-mcp"args = []

{  "mcpServers": {    "clef-mcp": { "command": "clef-mcp", "args": [] }  }}

{  "mcp": {    "servers": {      "clef-mcp": { "command": "clef-mcp", "args": [], "type": "stdio" }    }  }}

Ready-made snippets: examples/.

Teach your agent (skill)

The schema tells the client what clef_decide accepts; agents also need to know when to reach for it and how to frame decisions. The bundled clef-decisions skill covers decision patterns, batching, criteria writing, distribution interpretation and error recovery:

clef-mcp setup                                                    # automaticcp -r skills/clef-decisions ~/.agents/skills/                     # manual, from repocp -r "$(npm root -g)/clef-mcp/skills/clef-decisions" ~/.agents/skills/  # from npm package

Architecture

flowchart LR    subgraph clients [MCP clients]        CC[Claude Code]        CX[Codex]        CU[Cursor]        ZC[ZCode]    end    clients -- MCP stdio --> S[clef-mcp<br/>validation · limits · structured errors]    S -- SystemOne adapter --> R[ClefRuntime<br/>llama.cpp subprocess<br/>127.0.0.1]    R -- single forward pass --> M[("Clef-Flash<br/>9B · GGUF · local")]    M -. probabilities .-> S -. strict JSON .-> clients

The ClefRuntime interface (load / decide / unload / health) isolates the engine: MLX or remote runtimes plug in without changing the MCP API. The wire format is POST /v1/systemone — the same contract across llama.cpp and other Clef runtimes.

CLI

clef-mcp              # run the MCP server on stdio (default command)clef-mcp install      # detect hardware → download model + runtime → verify checksum → verify inferenceclef-mcp setup        # register the MCP server + agent skill in zcode / claude-code / codex / cursorclef-mcp models       # list models/quantizations and install statusclef-mcp status       # runtime, model, memory summaryclef-mcp doctor       # full diagnosis (platform, RAM, GPU, binary, model, checksum*, inference, MCP config)clef-mcp uninstall    # remove the model (and optionally the managed runtime)clef-mcp evals        # run the evaluation dataset against the installed model

Flags: install --quant Q8_0 --yes --skip-probe, install --setup, setup --clients zcode,cursor --no-skill, doctor --deep (re-hash the model file), uninstall --runtime --yes.

Runtimes: llama.cpp and MLX

Two local runtimes behind the same ClefRuntime interface:

Switch at runtime with CLEF_RUNTIME=mlx (must be set for the MCP server process — e.g. in the client's env block). Both speak the same POST /v1/systemone contract. The MLX snapshot is fetched into CLEF_HOME via a uv-managed huggingface_hub (no global Python state) at a pinned revision.

Configuration

Runtime resolution: CLEF_LLAMA_BIN → managed binary in CLEF_HOME/runtime → llama-server on PATH.

Storage: CLEF_HOME/models/<model>/<quant>/ (model + manifest.json with repo/revision/sha256/license) and CLEF_HOME/runtime/llama.cpp/.

The model is downloaded from the pinned official GGUF conversion (ggml-org/Clef-Flash-GGUF) and sha256-verified against Hugging Face's content hash. It is never repackaged by clef-mcp. Also listed in the official MCP Registry as io.github.HighlyLoadedEgo/clef-mcp.

Error handling

{  "error": {    "code": "MODEL_NOT_INSTALLED",    "message": "Clef model \"clef-flash\" is not installed.",    "hint": "Run `clef-mcp install`."  }}

Codes: MODEL_NOT_INSTALLED, MODEL_LOAD_FAILED, RUNTIME_NOT_FOUND, RUNTIME_INIT_FAILED, RUNTIME_NOT_SUPPORTED, INVALID_INPUT, CLEF_INFERENCE_FAILED, UNSUPPORTED_PLATFORM, OUT_OF_MEMORY, CHECKSUM_MISMATCH, DOWNLOAD_FAILED. Input exceeding the 16k-token model context is rejected with a hint to reduce the state.

Security & data handling

• No network servers, no telemetry, no accounts; everything runs locally.
• The model downloads only on an explicit install, over HTTPS, checksum-verified.
• state content is passed to the model as data; the server never executes or instruction-interprets it.
• Filesystem access is limited to CLEF_HOME (plus reading standard MCP client config paths in doctor).
• The managed runtime is the official llama.cpp build; pin it with CLEF_LLAMA_RELEASE_TAG.

See SECURITY.md for the full policy.

Development

npm installnpm run buildnpm test          # unit + integration (fake llama-server, no model needed)npm run evals     # needs an installed model; exit code reflects pass rate

See CONTRIBUTING.md and tests/evals/dataset.jsonl.

License

• Code: Apache-2.0.
• Clef / Clef-Flash model: © Cloudflare, Apache-2.0 — see NOTICE.
• llama.cpp runtime: © its authors, MIT-licensed; downloaded as an official prebuilt binary.