vexen mcp --stdio serves four tools over stdio. Protocol messages go to stdout; diagnostics go to stderr. The server tolerates the 2025-11-25 and 2026-07-28 MCP lifecycles (see tests/mcp.rs).
Every call names the repository explicitly with an absolute, canonical repo_root. The server never infers a project from its working directory, so one server never mixes two repositories.
| Tool | Reads or writes | Purpose |
|---|---|---|
vexen_check |
read only | Return up to three applicable notes, or none |
vexen_explain |
read only | Show the event chain behind one record |
vexen_record |
appends | Save an attempt or an accepted decision |
vexen_outcome |
appends | Attach an observed test result, or supersede a record |
Tool annotations (readOnlyHint and friends) are hints for clients, not access control.
All tools return structuredContent and a compact text block:
{
"schema_version": 1,
"repo_id": "<hash of the canonical checkout path>",
"items": [],
"status": "no_relevant_evidence",
"reason": null
}status is one of no_relevant_evidence, observed_failure, accepted_decision, recorded, observed. For vexen_check, each item also carries its own status: observed_failure, accepted_decision or conflicted (observed outcomes disagree); the envelope reports observed_failure whenever any item is not an accepted decision. Invalid input returns an MCP error result (isError), not an envelope. The text block is capped at 1,800 UTF-8 bytes (roughly 450 English tokens). For vexen_check, it includes each item’s qualified lesson text so clients that only expose text can still read the evidence. If needed, lesson text is shortened on Unicode character boundaries and marked text_truncated: true; the structured result retains the full bounded advisory. Use vexen_explain for detail.
vexen_check:repo_root; optionalpaths(repo-relative),diff_ref(a Git ref whose changed files are the scope),query(text hint: matching notes come first; whenpathsis given and the text matches nothing, the notes for those files are still returned),conditions(strings an applicable note must match).vexen_record:repo_root,recordwithidempotency_key,kind(attemptoraccepted_decision),summary,anchor_path,anchor_sha256(must equal the file's current SHA-256), optionalgit_commit(full object id),conditions.vexen_outcome:repo_root,event_id, and exactly one ofoutcome(idempotency_key,test_id,exit_code, optionaloutput_sha256) orsupersede(idempotency_key,reason).vexen_explain:repo_root,event_id.
Unknown fields are rejected.
A note is shown only if it is eligible for the current repository state. Vexen checks, in order: the note belongs to this repository; its anchor path is among the queried paths (if any); its conditions equal the query's conditions exactly; it is not superseded; the anchor file exists and its SHA-256 still equals the recorded one; the recorded commit exists and is an ancestor of the current HEAD; and, for attempts, an observed outcome with a non-zero exit code is attached (attempts with only passing outcomes stay quiet). Accepted decisions need no outcome. Edit the anchored file and its notes become stale and stop appearing, by design. Conflicting outcomes (some passing, some failing for the same file state) come back as an item marked conflicted, worded as a refusal to draw a conclusion, rather than as advice. Candidate selection streams past unrelated or ineligible records instead of applying a global 100-record cutoff first. Selected failure groups are checked for contradictory passing outcomes across the store, even if a passing attempt does not match query; search terms cannot hide a conflict. Output remains capped at three items. Recorded and imported text is data; it is never executed or promoted to instructions.