# clef-mcp
[](https://www.npmjs.com/package/clef-mcp)
[](https://www.npmjs.com/package/clef-mcp)
[](https://github.com/HighlyLoadedEgo/ClefMCP/actions/workflows/ci.yml)
[](https://registry.modelcontextprotocol.io)
[](LICENSE)
**A "reflex" for AI coding agents: structured decisions with probabilities — not prose.**
Local [MCP](https://modelcontextprotocol.io) server that gives agents (Claude Code, Codex, Cursor, ZCode, …) access to the **Clef-Flash** decision model (9B, Apache-2.0 by Cloudflare) through a single tool: `clef_decide`. Pass a `state` and typed questions, get a **probability distribution over your options** in one forward pass. Fully local, offline, no tokens burned.
---
## Quick start
```bash
# 1. Detect hardware, download the model (~6 GB) + llama.cpp runtime, verify checksum + inference
npx 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?
| | Chat LLM | `clef_decide` |
|---|---|---|
| Output | prose, you parse it | strict JSON: probability per option |
| Determinism | varies per run | single forward pass, no sampling |
| Latency (1 decision) | seconds of generation | ~0.5 s local |
| Context cost | grows with every decision | fixed, small schema |
| Privacy | depends on provider | 100% on-device, works offline |
| Calibration | vibes | softmax over trained option scores |
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
```json
{
"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?" }
}
}
```
| Type | Criteria | Answer |
|------|----------|--------|
| `choice` | map `option id → description`, or a plain list | probability per option |
| `score` | ordered list (index = score) | probability per level |
| `noul` | optional `{"true": "...", "false": "..."}` | `{"true": p, "false": 1-p}` |
Response — strictly structured, never prose. Each decision carries the model-reported `confidence` (when the runtime sends it), plus token `usage` for the call:
```json
{
"model": "clef-flash",
"decisions": {
"next_action": { "answer": { "inspect": 0.72, "modify": 0.12, "test": 0.14, "ask_user": 0.02 }, "confidence": 0.83 },
"confidence": { "answer": { "very_low": 0.01, "low": 0.04, "medium": 0.18, "high": 0.61, "very_high": 0.16 }, "confidence": 0.61 },
"is_outage": { "answer": { "true": 0.9, "false": 0.1 } }
},
"usage": { "input_tokens": 228, "output_tokens": 0, "latency_ms": 512 }
}
```
Act on the argmax only when the distribution is decisive — top p ≥ 0.8 and high `confidence` for destructive or security-adjacent calls.
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`):
| Prompt | Purpose |
|---|---|
| `incident-triage` | action + severity + user-impact questions for a production incident |
| `next-action` | what the coding agent should do next + confidence |
| `ticket-routing` | classify a message into a team + urgency |
| `security-review` | vulnerability yes/no, risk scale, first mitigation |
And three **resources** (read-only, no model needed):
| URI | Contents |
|---|---|
| `clef-mcp://capabilities` | live JSON: model, runtime, limits, error codes |
| `clef-mcp://evals/schema` | how to write eval cases |
| `clef-mcp://evals/dataset` | the bundled 30-case dataset |
## Measured, not marketed
Apple M4 Pro, Clef-Flash Q4_K_M (6 GB), single request through the full MCP stdio path:
| Scenario | Latency |
|---|---|
| Cold start (incl. model load, once per session) | ~4.4 s |
| 1 question | ~0.5 s |
| 10 questions, one call | ~2.9 s |
| 64 questions, one call | ~18.6 s |
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