Clef MCP

clef-mcp

Local decisions for AI agents. Reusable classification for your datasets.

Run Clef-Flash (9B, Apache-2.0 by Cloudflare) locally. Give coding agents a structured MCP decision tool, or classify JSONL/CSV datasets with YAML profiles. Get probabilities and explicit review results instead of generated prose. Inference stays on your machine.

---

Quick start

Requires Node.js 20+ and enough memory for the selected model (16 GB recommended for Q4_K_M). The default model download is approximately 6 GB; subsequent inference runs offline.

npm install -g clef-mcp

clef-mcp install

Choose your workflow:

The MCP server starts with clef-mcp (stdio). Only install downloads model/runtime files. You can also use npx -y clef-mcp instead of a global install; npx -y clef-mcp install --setup combines model installation and client registration.

Classify JSONL/CSV with a YAML profile

Define a task once, then apply it to separate records. The model loads once for the whole batch; a separate daemon is not required.

Save this as support-routing.yaml:

schema_version: 1

name: support-routing instructions: Classify the current support request into exactly one department. labels: billing: Payments, refunds, invoices and subscription charges technical: Errors, outages, installation and integration problems other: Requests outside billing and technical support input: id_field: id fields: [subject, body] policy: min_probability: 0.80 min_margin: 0.15

Save tickets.jsonl (one object per line):

{"id":"001","subject":"Duplicate charge","body":"Please refund my duplicate subscription payment."}

{"id":"002","subject":"Checkout crashes","body":"The payment page returns an error."}

Or use tickets.csv with a header row:

id,subject,body

001,Duplicate charge,Please refund my duplicate subscription payment. 002,Checkout crashes,The payment page returns an error.

clef-mcp classify tickets.jsonl --profile support-routing.yaml --output results.jsonl

clef-mcp classify tickets.csv --profile support-routing.yaml --output csv-results.jsonl

stdout carries JSONL; summaries and diagnostics go to stderr

cat tickets.jsonl | clef-mcp classify - --profile support-routing.yaml

Extension override, including CSV on stdin

cat tickets.csv | clef-mcp classify - --format csv --profile support-routing.yaml

Runnable files also ship in examples/classify/.

Profile fields

Examples are data supplied alongside the current record; they do not train or modify model weights. Unknown fields, duplicate YAML keys, aliases, merge keys, unsupported tags and non-JSON values are rejected. Label IDs use the same character rules as profile names, with a 128-character limit; prototype-shaped reserved keys are rejected. Missing selected fields produce row errors.

Accepted results and needs_review

Illustrative results (actual probabilities depend on your data and runtime):

{"row":1,"id":"001","profile":"support-routing","model":"clef-flash","status":"classified","label":"billing","suggested_label":"billing","probability":0.92,"margin":0.87,"probabilities":{"billing":0.92,"technical":0.05,"other":0.03},"review_reasons":[]}

{"row":2,"id":"002","profile":"support-routing","model":"clef-flash","status":"needs_review","label":null,"suggested_label":"technical","probability":0.48,"margin":0.06,"probabilities":{"billing":0.42,"technical":0.48,"other":0.10},"review_reasons":["low_probability","low_margin"]}

classified means all configured thresholds passed. needs_review keeps the suggestion and full distribution but sets label: null. Reasons are low_probability, low_margin, tie, low_confidence or missing_confidence. Exact ties always require review, including when thresholds are zero. Comparisons are inclusive at the threshold. Results may include model confidence and token usage when available.

Winning probability, probability margin and model-reported confidence are different quantities. These thresholds are routing policy, not a calibrated accuracy guarantee. Check them on representative labeled data before automating decisions. Classification does not grant authorization or execute actions.

Invalid JSONL objects and missing fields produce status: "error" rows and processing continues. Runtime failures stop the run; they are never converted to review decisions. Output includes identifiers and results, not a copy of the original record.

Resume, formats and limits

clef-mcp classify tickets.jsonl --profile support-routing.yaml --output results.jsonl --resume

File output creates private results.jsonl and results.jsonl.meta.json files. The sidecar fingerprints the full input, validated profile, effective model, runtime and format. Resume requires all of these to match. Use a new output path after changing data or thresholds; existing files are never silently overwritten. Input must stay unchanged while a run is active.

Resume skips the contiguous committed prefix, including committed error rows; it does not retry those errors. An incomplete final write is discarded, while corruption in a complete row is rejected. Resume requires regular file input and --output; stdin/stdout resume is unsupported. A local lock prevents simultaneous writers. Dead local writer locks can be reclaimed; active, foreign-host or unverifiable locks are preserved. A crash during lock acquisition may leave .lock.claim, which requires inspection before manual removal.

JSONL accepts objects, ignores blank lines and supports UTF-8 BOM/CRLF. CSV supports quoted commas, escaped quotes and multiline fields; headers must be nonempty and unique, with consistent column counts. CSV cells remain strings, preserving IDs such as 001. Format defaults to .jsonl/.csv, or JSONL for stdin; other extensions need --format.

Profiles and logical records are limited to 1 MiB, YAML nesting to 64 levels, selected/CSV fields to 1000, and examples to 20. Existing instruction/criteria/state limits and the model's 16k-token context also apply; selected fields and examples share that context. Oversized JSONL rows are reported as row errors. Broken/oversized CSV syntax stops the run because record boundaries cannot be recovered reliably.

Update

npm install -g clef-mcp@latest

Restart MCP clients and any existing daemon after updating. An already installed model does not need another download.

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. Each decision carries the model-reported confidence (when the runtime sends it), plus token usage for the call:

{

"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):

| incident-triage | action + severity + user-impa