An MCP server that gives your coding agent eleven judgment tools backed by TypeSafe's Jev model. The agent hands a tool some evidence and a question it can enumerate: is this claim supported, is this page safe to read, which of these files answers the question, did this patch finish the task. Jev answers with probabilities, usually in under a second (median 464.6 ms round trip in the recorded bench), for about $0.025 per 1,000 decisions on the recorded classify run — and on that benchmark every answer the policy auto-accepted was correct, with the misses routed to review instead of through. Policy turns the probabilities into one of three actions: auto (proceed), review (check it another way), or escalate (stop). The numbers and their sources: Measured results.

Use it for checks that have a fixed set of answers. When the step needs new text, code, or options you cannot list, the agent should write it itself.

Install

You need Python 3.12+, uv, a POSIX system (Linux or macOS), and a TypeSafe API key from console.typesafe.ai. The published package is on PyPI, and these three commands configure your agents to launch that pinned package (ADR-0051):

uvx --from 'jev-judge-mcp[typesafe]' jev-judge-mcp setup     # verify your key, then store it
uvx --from 'jev-judge-mcp[typesafe]' jev-judge-mcp install   # add the server to your agents
uvx --from 'jev-judge-mcp[typesafe]' jev-judge-mcp doctor    # check the configuration, offline

Every entry the installer writes also requests a Python the package itself declares — --python '>=3.12', taken from the package's Requires-Python metadata (ADR-0053). On a machine whose first interpreter is older (Ubuntu 22.04's 3.10, macOS system 3.9), uv picks or downloads one that qualifies instead of refusing to start the server.

More installer options

To develop against an unreleased tree, install from a clone and pass --from-checkout, which pins the entries at your checkout instead of the PyPI package:

git clone https://github.com/PyModel/jev-judge-mcp
cd jev-judge-mcp
uv sync --extra typesafe
uv run jev-judge-mcp install --from-checkout

That extra is only for running the server. Development and make typecheck need the full sync: uv sync --locked --all-extras — a plain uv sync fails make typecheck with confusing Import "typesafe_sdk" could not be resolved errors.

Running install from an unreleased clone without --from-checkout? It prints a note that the pinned PyPI build does not include your local changes, and points here. The post-write check then exercises the published build, not your tree.

Installed from a clone earlier? One plain re-run of install rewrites the entries this installer owns to the version-pinned PyPI spec — that is the whole migration. Entries the installer does not own are left alone.

Restart your agent. The tools show up as jev_verify, jev_gate, and so on (mcp__jev__* in Claude Code).

setup reads the key from TYPESAFE_API_KEY, or asks for it at a hidden prompt. It never takes the key as an argument, so the key stays out of your shell history. It makes one live call to check the key and writes nothing if TypeSafe rejects it. A good key goes to ~/.config/jev-mcp/key, readable only by you. The server uses that file whenever TYPESAFE_API_KEY is unset, so agents you start without exporting the key still work. When the variable is set, it wins.

install finds the agents on your machine, shows what it will change, and asks before writing. It supports Claude Code, Claude Desktop, Codex (CLI and the ChatGPT app), Cursor, OpenCode, Pi, omp, and Pythinker.

uvx --from 'jev-judge-mcp[typesafe]' jev-judge-mcp install --dry-run    # show the plan, write nothing
uvx --from 'jev-judge-mcp[typesafe]' jev-judge-mcp install -a claude-code    # one agent (repeatable)
uvx --from 'jev-judge-mcp[typesafe]' jev-judge-mcp install --remove    # undo what install wrote

Terminal agents get a reference to TYPESAFE_API_KEY, never the key itself. Desktop apps don't see your shell's environment. Claude Desktop (macOS only) is skipped unless you pass --desktop-key, which writes the key into that app's config file. The same flag writes the key into the Codex and Pythinker files when the ChatGPT or Pythinker desktop app shares them; without it, install says that app has no key. The installer warns if a file holding the key ends up readable by other users. Pi also needs its MCP adapter first: pi install npm:pi-mcp-adapter.

Register the server by hand

<uvx> is the absolute path of uvx. <spec> is jev-judge-mcp[typesafe]==<version> (the version-pinned PyPI package, what install writes by default) or your checkout's absolute path plus [typesafe], for example /home/me/jev-judge-mcp[typesafe]. --python '>=3.12' is what install derives from the package metadata; keep it when you register by hand.

Claude Code (~/.claude.json), omp (~/.omp/agent/mcp.json), Cursor (~/.cursor/mcp.json), and Pi (~/.pi/agent/mcp.json) use the same shape. Claude Code and omp also add "type": "stdio". Pi also adds the three exposure keys below; without them pi-mcp-adapter keeps the server lazy and proxy-only and the tools stay out of the model's initial list (ADR-0036).

{
  "mcpServers": {
    "jev": {
      "command": "<uvx>",
      "args": ["--python", ">=3.12", "--from", "<spec>", "jev-judge-mcp"],
      "env": {"TYPESAFE_API_KEY": "${TYPESAFE_API_KEY}"}
    }
  }
}

Pi's full entry:

{
  "mcpServers": {
    "jev": {
      "command": "<uvx>",
      "args": ["--python", ">=3.12", "--from", "<spec>", "jev-judge-mcp"],
      "env": {"TYPESAFE_API_KEY": "${TYPESAFE_API_KEY}"},
      "lifecycle": "eager",
      "directTools": true,
      "toolPrefix": "none"
    }
  }
}

lifecycle: "eager" connects at startup, directTools: true registers every tool individually, and toolPrefix: "none" keeps the published names (jev_verify, ...), so the tools sit in the model's initial tool list, callable like any builtin.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json) uses the same shape with the key itself in env. Pythinker (~/.pythinker-code/mcp.json) uses it without env, unless the Pythinker desktop app shares the file and needs the key there.

Codex CLI and the ChatGPT app share ~/.codex/config.toml:

[mcp_servers.jev]
command = "<uvx>"
args = ["--python", ">=3.12", "--from", "<spec>", "jev-judge-mcp"]
env_vars = ["TYPESAFE_API_KEY"]

When the ChatGPT app shares that file, it also needs the key itself in an [mcp_servers.jev.env] table with TYPESAFE_API_KEY = "<key>".

OpenCode (~/.config/opencode/opencode.json):

{
  "mcp": {
    "jev": {
      "type": "local",
      "command": ["<uvx>", "--python", ">=3.12", "--from", "<spec>", "jev-judge-mcp"],
      "environment": {"TYPESAFE_API_KEY": "{env:TYPESAFE_API_KEY}"}
    }
  }
}

Set up with your agent

Paste this into Claude Code, Codex, Cursor, OpenCode, Pi, omp, or any agent, and it configures the server for you: stores the key, installs and verifies the server entry, and adds the usage rules to its own instruction file. The key never passes through the chat — setup reads TYPESAFE_API_KEY from the environment or asks at a hidden prompt.

Set up the jev-judge-mcp judgment tools for me, then add their usage rules to your instructions.

1. Run `uvx --from 'jev-judge-mcp[typesafe]' jev-judge-mcp setup`. It verifies my TypeSafe key:
   it reads TYPESAFE_API_KEY from the environment or asks at a hidden prompt. Never ask me for the
   key, echo it, or write it into chat, a prompt, or any instruction file.
2. Run `uvx --from 'jev-judge-mcp[typesafe]' jev-judge-mcp install --dry-run` and show me the plan.
   Wait for my confirmation in chat before anything is written. On Pi, run
   `pi install npm:pi-mcp-adapter` first. Once I confirm, run
   `uvx --from 'jev-judge-mcp[typesafe]' jev-judge-mcp install -a <your agent> -y`, naming your own
   agent (claude-code, codex, cursor, opencode, pi, omp, or pythinker); `-y` skips the CLI prompt
   because the confirmation happened in chat.
3. Run `uvx --from 'jev-judge-mcp[typesafe]' jev-judge-mcp doctor` and fix anything it reports.
4. Tell me to restart you. After the restart, confirm the jev tools are in your tool list.
5. Add the "Fast judgment checks — and when to skip them" rule block to your main instruction file —
   CLAUDE.md for Claude Code, AGENTS.md for Codex and most others. The block follows this prompt
   (it is also tracked at docs/agent-rules.md in the jev-judge-mcp repo; ask me to paste it if you
   do not have it). Read the instruction file first: never duplicate an existing Jev rules block,
   and replace a stale one.

The rule block the prompt adds. One tracked copy lives at docs/agent-rules.md; the copy below is pinned to it by a contract test, so paste either:

<!-- Source of truth: jev-judge-mcp docs/agent-rules.md. The README copy and every cap below are
     pinned by tests/contract/test_docs_alignment.py. Depth: docs/skills/jev-mcp/SKILL.md
     (which tool fits which step) and docs/guidance.md (how to shape the call). -->

### Fast judgment checks — and when to skip them

Jev (TypeSafe) is a small judgment model served by the jev-judge-mcp MCP server: its tools take
evidence plus a question with a fixed answer set and return typed probabilities, not text. Call a
`jev_*` tool (`mcp__jev__*` in Claude Code) when a step judges material you already have — a
bounded check, a pick-one, a rank, a match-the-claim — and an independent typed judgment is worth
an extra tool turn. Skip it on steps you can settle by reading what is already on screen, or that
your tests already cover: the extra turn costs agent wall time, and the recorded studies measured
agents slower with Jev, never faster.

| Tool | Use it to | Caps |
|------|-----------|--------|
| `jev_verify` | Check claims against evidence → verified / contradicted / unsupported. Subagent or research reports, PR descriptions, your own "done" claims | no length bound on claims or evidence |
| `jev_gate` | Before declaring done: the patch plus its completion claims checked against diff and test-log evidence in one call → auto / review / escalate | ≤16 claims, ≤16 evidence items; 200,000 units of evidence, 50,000 units per diff or test log |
| `jev_review` | Score a diff against the request: correctness, spec match, test gap, blast radius, `safe_to_apply` | 50,000 units per document, truncated |
| `jev_screen` | Screen fetched or pasted external text for prompt injection and relevance **before** reading it → pass / review / block / skip | no length bound |
| `jev_compare` | Two passages: same_fact / contradicts / different_facts, optional per-aspect checks. Docs vs code drift, changelog vs diff | 20,000 units per passage, ≤10 aspects |
| `jev_find` | Which of up to 250 candidates (files, notes, hits) answers the question, plus whether any candidate matches at all | ≤250 candidates, 2,000 units per candidate |
| `jev_rerank` | A relevance score for every candidate, full ordering. Triage search hits and grep results | ≤250 candidates |
| `jev_classify` | Bucket items into a shared class catalog: triage, routing, labeling | ≤64 items, ≤250 classes |
| `jev_decide` | One bounded choice among 2–6 options with evidence and priorities; escape hatches `ask_user` / `investigate` / `none` | 2–6 options |
| `jev_extract` | Your regex proposes candidates, Jev picks, the value comes back verbatim (versions, prices, dates, IDs) | 50,000 units per document, ≤32 fields |
| `jev_score` | Grade severity or risk on your own ordered rubric; threshold the level, never interpolate a magnitude between levels | 2–10 levels |

Caps are UTF-16 code units, frozen in the server's `limits.py`.

Rules:

- **Not for open work, not for trivia.** No Jev call for new prose, code, or research whose
  answers you cannot list — write those yourself. And skip Jev on steps you already know the
  answer to.
- **Evidence in, not your verdict.** State holds raw diffs, logs, and excerpts — not your
  conclusion. A conclusion written into state gets agreement, not a judgment.
- **Act on `action`:** `auto` → proceed · `review` → confirm with tests, source reading, or a
  stronger check · `escalate` → stop and surface it. `invalid_response` → the row is unjudged;
  leave it without a verdict.
- **Jev screens; it never proves.** A Jev check never replaces running the tests, lint, or types.
  A `jev_gate` `auto` is necessary before "done", not sufficient.
- **Batch.** One call with every claim, candidate, or item beats many calls; questions inside one
  request cannot see each other's answers.
- **No re-asks.** Do not re-ask an unchanged question hoping for a better answer; gather better
  evidence instead.
- **Failures are one line.** Tool error or missing key (`TYPESAFE_API_KEY`): say so in one line,
  then fall back to normal checks.

Prefer to do it yourself? The three commands in Install stay the manual path, and the block above pastes into CLAUDE.md or AGENTS.md by hand just as well.

What to use it for

Ask your agent in plain words. It picks the tool, or you can name it.

You want to	Tool	You get
Check that the agent's "done" matches the diff and the test log	jev_gate	one ship decision over the patch and each completion claim
Check claims in a summary or PR description against the sources	jev_verify	verified, contradicted, or unsupported for each claim
Screen a fetched web page for prompt injection before reading it	jev_screen	pass, review, block, or skip
Review a patch against the request	jev_review	correctness, spec match, test gaps, blast radius
Spot drift between docs and code, or a changelog and a diff	jev_compare	same fact, contradiction, or different facts
Find the file or note that answers a question	jev_find	the best match, plus whether anything matches at all
Rank search hits or grep results	jev_rerank	a relevance score for every candidate, sorted
Route tickets or label many items at once	jev_classify	one class per item from your catalog
Pick one option, or decide whether to keep waiting on a slow command	jev_decide	your option, or ask_user / investigate / none
Grade severity or risk on your own scale	jev_score	a position on your 2 to 10 levels, with the distribution; threshold it in code, since positions between levels are weakly calibrated
Pull a version, date, or price out of a document	jev_extract	a value copied from a match of your regex, or null

For example, "use jev_verify to check your summary against the changelog" returns one row per claim:

{
  "claim": "The setup command accepts the API key as a command-line argument.",
  "verdict": "contradicted",
  "probabilities": { "supports": 0, "contradicts": 1, "says_nothing": 0 },
  "confidence": 1,
  "action": "auto",
  "supporting_evidence": "setup.py"
}

Jev sees only what the agent passes in the call, so the agent has to include the evidence. docs/skills/jev-mcp/SKILL.md is a skill you can give your agent: it covers which tool fits which step and what to do with each action. How to write the state and the questions so the probabilities come back usable — named fields over positional arrays, where cutting text costs, option descriptions, rules out of the question, and thresholds that rise with risk — is in the caller guide, and a per-tool card states each tool's intended use, what recorded evidence exists, and its weak spots. Honor action, not a grep of verdict. jev-judge-mcp judge and jev-judge-mcp gate are the path for a client that does not speak MCP. JEV_MCP_MODEL pins the model. Allow rules for Claude Code are printed by doctor, and opt-in setups for Claude Code, Codex, and Pi are in the harness samples. Hook protocols for OpenCode, Grok, Gemini, Kimi, and Cursor are unverified; the CLI does not branch on them.

Measured results

Three paid studies, all descriptive, with small samples and no significance test. Jev itself is fast, cheap, and right when it commits; the agent around it pays for the extra tool turn. Those are different measurements, so they are reported separately. Release-by-release evidence — certified operating points and regressions — is recorded in docs/EVIDENCE.md.

Jev itself: round trip, cost, and decision quality

Round trip — median 464.6 ms, p90 1245.3 ms, p95 1468.8 ms over 157 calls (evals/reports/bench150.md).

Decision quality — on the public JevBench subset (2026-09-26, jev-1.13.0 through jev_classify): 89/92 items correct — easy 36/36, original 36/36, hard 17/20. The policy auto-accepted 86 answers and 86/86 were correct; the 6 answers it routed to review hold all 3 misses, so no wrong answer was auto-accepted. Scorer: selective_accuracy_auto 1.0, auto_coverage 0.935, micro_f1 0.9727. JevBench's own v1.2 reference for the same model — results/v1.2/jevbench-v1.2-per-task.json at JevBench commit 1bcc55eb — is also correct on 89/92 of these items; the accuracy count is the like-for-like part, its confidences are not policy-comparable. This is the classify-compatible subset, not JevBench's 231-item leaderboard. Details: evals/reports/jevbench-public.md.

Cost — the JevBench-subset run spent $0.002281 on 92 calls (54,308 billed input tokens), about $0.025 per 1,000 decisions at that packing; bench150's forced arm — a different packing — spent $0.0060 over 150 calls, $0.040 per 1,000.

The agent around Jev

A Jev call is an extra tool turn in the agent's loop, and that is where the wall time goes: Jev's own round trip is sub-second (above), while the recorded studies measured both agents slower with Jev at the same solve rates. Neither study measured an accuracy gain.

On 150 questions with Pi (opencode-go/deepseek-v4.1-flash), forcing a Jev call added 10.4 s median wall time per task. Letting the agent choose left Jev uncalled on all 150. Accuracy was not measured. Details: evals/reports/bench150.md.

arm	median wall s	p95	called Jev	agent spend
A direct	3.06	6.17	0/150	$0.0928
B automatic	2.91	8.09	0/150	$0.0955
C forced	13.95	28.67	150/150	$0.2904

The agent outcome study ran on 2026-09-23 with jev-1.13.0: three tasks, three repeats per arm, with and without Jev. Both agents solved the same pairs either way and picked the right decision on every run. Both were slower with Jev. One Pi pair is excluded because its with-Jev run never called Jev. Details, raw records, and the chart script: docs/evals/.

agent	solved without / with Jev	median time to correct, without / with	extra wall time with Jev (paired median)	spend
Claude Code (claude-sonnet-5)	6/9 / 6/9	14.6 s / 18.3 s	+4.6 s	$1.4953
Pi (ds4/glm-5.3-flash, local)	6/8 / 6/8	49.4 s / 127.8 s	+85.8 s	$0.0006

Configuration

The server reads environment variables only. It does not load a .env file.

Variable	Default	What it does
TYPESAFE_API_KEY	unset	TypeSafe key; takes priority over the stored key
JEV_MCP_KEY_FILE	~/.config/jev-mcp/key	where setup stores the key and the server reads it
JEV_PROVIDER	auto	auto takes the first provider with credentials: typesafe, openrouter, cloudflare, compatible. The reference's vercel provider (AI_GATEWAY_API_KEY) is not supported
JEV_MCP_MODEL	jev-latest	Jev model to ask
JEV_MCP_CACHE	off	replay identical requests from disk at no API cost; leave it off when answers must be fresh, and delete the directory to clear it
JEV_MCP_CACHE_DIR	~/.cache/jev-mcp	where the cache lives
JEV_MCP_CACHE_MAX_ENTRIES	4096	cache entry cap; a store past it evicts the oldest entries first (0 disables)
JEV_MCP_CACHE_TTL_SECONDS	604800	cache entry age in seconds before it stops replaying and is deleted (0 disables)
JEV_MCP_TRANSPORT	stdio	streamable-http is experimental and binds JEV_MCP_HTTP_HOST:JEV_MCP_HTTP_PORT, default 127.0.0.1:8088. Port 8000 is often already taken, so it is not the default
JEV_MCP_HTTP_TOKEN	unset	bearer token for the HTTP transport; required on every request, and required for any non-loopback JEV_MCP_HTTP_HOST
JEV_MCP_LOG_LEVEL	INFO	logs go to stderr
JEV_MCP_MAX_INFLIGHT	0	cap on concurrent provider requests per process; extra calls wait instead of fanning out (0 = no cap)

Operator notes

Every input cap and default is tabulated in docs/reference/limits.md, machine-checked against the code; the page also states the error code each refusal produces. Two parity-sanctioned facts — the reference server behaves the same way — that show up as cost or latency:

• jev_verify and jev_screen put no length bound on their input. The claims, evidence, or page text are sent to the provider in one request, however large, so token cost and latency scale with what the caller passes. Bound the text at the call site when it is not yours.
• Requests over stdio still carry no whole-call provider deadline (the sanctioned divergence stdio-attempt-deadline): the client's cancellation remains the recovery path for a call. Every provider attempt is bounded, though (ADR-0057): a hung connection times out after 30 s and a transient failure — connection errors, timeouts, 408/429/5xx — is retried, up to 3 attempts with capped exponential backoff (server Retry-After hints honored, capped at 5 s) inside a 90 s budget. A call whose attempts all fail reports the provider, the attempt count, and the last failure.
• initialize's serverInfo.version, the one startup log line, and jev-judge-mcp --version report the same build. A wheel, and a checkout whose HEAD is the tag v<version>, report that version. Any other git checkout reports <version>+g<short sha> (ADR-0054). The wire name stays jev-mcp (ADR-0049).
• jev_rerank returns every candidate in ranked, highest relevance first. relevance is that candidate's probability, to four decimal places. The response has no spread field. A flat band of low values means the candidates were not distinguishable: treat the order as weak, and read ranked[].relevance rather than the rank numbers.
• jev_review and jev_gate escalate when the lowest rubric confidence, or safe_to_apply, is below thresholds.review_at (the reference rule; default 0.5). That includes a low-confidence ancillary score such as test_gap on a patch the other scores accept. Escalate here is uncertainty, not a finding that the patch is wrong. The driving score is the scores entry — under review on jev_gate — whose confidence is below thresholds.review_at. Compare safe_to_apply to the same threshold. The response does not name the driver; those two fields do.
• Per-tool weak spots and what recorded evidence exists for each tool are in docs/tools.md; per-release evidence, including certified operating points, is recorded in docs/EVIDENCE.md.

Running over HTTP (experimental)

The HTTP transport is Tier B experimental: it has no reliability contract and no admission control, and it is not covered by the parity suite. Only 127.0.0.1, localhost, and ::1 are exempt from the token: exactly those hosts get the SDK's automatic Host/Origin validation. Every other host — 127.9.9.9, 0:0:0:0:0:0:0:1, 0.0.0.0, a LAN address, a hostname — refuses to start unless JEV_MCP_HTTP_TOKEN is set, because every tool call would otherwise spend your provider key on behalf of anyone who can reach the port.

The default port is 8088, not 8000: 8000 is often already taken by a local model server or another dev server (ADR-0055). If 8088 is taken too, the process retries that same port for a couple of seconds and then exits non-zero with one line naming JEV_MCP_HTTP_PORT and the port. It does not pick a different port, and it leaves no listener behind. A port taken between that check and the listen refuses the same way, because the server binds the port itself and hands the sockets to the listener. Set the variable to a free port.

Generate a token:

python -c "import secrets; print(secrets.token_urlsafe(32))"

Run the server with it:

JEV_MCP_TRANSPORT=streamable-http JEV_MCP_HTTP_HOST=0.0.0.0 JEV_MCP_HTTP_TOKEN=<token> jev-judge-mcp

Every HTTP request must then carry the token; a request without it, or with a wrong one, gets 401 before any tool runs:

curl -H "Authorization: Bearer <token>" \
  -H "Accept: application/json, text/event-stream" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"example","version":"0"}}}' \
  http://127.0.0.1:8088/mcp

Architecture

One diagram covers the whole server: the tool-call loop from tools/call to the returned action text, the fail-closed answer path, and the local CLI commands around it (install, setup, hook gate, doctor) with the stored key file and the optional response cache. Open docs/architecture.html for the interactive version (guided views, dark mode, node search, relationship tracing).

About this project

This is a Python rewrite of the TypeScript @jkudish/jev-mcp 0.5.0. The ten reference tools match it on the wire, checked by recorded parity fixtures; jev_score is an addition. Vocabulary is in docs/CONTEXT.md, decisions in docs/adr/, and security notes in SECURITY.md. Windows is not supported; the server exits at startup on a non-POSIX platform.

uv sync --locked --all-extras   # development needs every extra; --extra typesafe alone only runs the server
make ci      # lint, types, unit, property, policy coverage, contract, parity, security, build, smoke, eval

make eval-live, make security-live, and JEV_AB_LIVE=1 make ab call paid services and stay off CI. Contribution notes are in CONTRIBUTING.md.

MIT license.