jev-judge-mcp

<div align="center"> <img src="./docs/readme/hero.png" alt="jev-judge-mcp, with a scales-of-justice emblem: typed judgment tools for MCP agents. Model judges, policy decides: auto, review, or escalate. A four-stage decision pipeline: check, find, decide, ship." width="100%" /> <p> <a href="https://github.com/PyModel/jev-judge-mcp/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/PyModel/jev-judge-mcp/ci.yml?branch=main&style=flat&label=CI&logo=githubactions&logoColor=white&labelColor=0a0a0f"></a> <a href="./pyproject.toml"><img alt="Version" src="https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fraw.githubusercontent.com%2FPyModel%2Fjev-judge-mcp%2Fmain%2Fpyproject.toml&query=%24.project.version&prefix=v&label=version&style=flat&labelColor=0a0a0f&color=ffc94d"></a> <a href="https://pepy.tech/projects/jev-judge-mcp?timeRange=threeMonths&amp;category=version&amp;includeCIDownloads=true&amp;granularity=weekly&amp;viewType=line&amp;versions=Total%2C0.*"><img alt="Downloads" src="https://img.shields.io/pepy/dt/jev-judge-mcp?style=flat&amp;label=downloads&amp;logo=pypi&amp;logoColor=white&amp;labelColor=0a0a0f"></a> <a href="https://www.python.org/"><img alt="Python 3.12+" src="https://img.shields.io/badge/python-3.12%2B-ff7b2e?style=flat&logo=python&logoColor=white&labelColor=0a0a0f"></a> <a href="https://modelcontextprotocol.io/"><img alt="MCP over stdio" src="https://img.shields.io/badge/MCP-stdio-b9e769?style=flat&logo=modelcontextprotocol&logoColor=white&labelColor=0a0a0f"></a> <a href="./LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-4fd8c4?style=flat&logo=opensourceinitiative&logoColor=white&labelColor=0a0a0f"></a> </p> </div>

An MCP server that gives your coding agent fifteen 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):

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

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.

<details> <summary><b>More installer options</b></summary>

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.

</details> <details> <summary><b>Register the server by hand</b></summary>

<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]. Keep the [typesafe] suffix: without it the package's TypeSafe SDK is missing, and a server started with a TypeSafe key present refuses to run with a one-line message instead of serving calls that all fail. --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}"}
    }
  }
}

</details>

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:

<details> <summary>Show the rule block</summary>

<!-- 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).
     the packaged jev skill (resource jev-skill://jev/SKILL.md) is the other skill:
     building an app on the Jev API, not these tools. -->

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

Jev (TypeSafe) is TypeSafe's flagship 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