jev-mcp

September 16, 2026 · View on GitHub

Jev provides typed judgments over a closed answer set in about 130 ms, with no text generation, through TypeSafe.

Install

Set TYPESAFE_API_KEY in the environment used by your MCP client, then run:

uvx --from git+https://github.com/blakestone-x/jev-mcp@v0.2.1 jev-mcp

Claude Code:

claude mcp add --scope user jev -e TYPESAFE_API_KEY=... -- uvx --from git+https://github.com/blakestone-x/jev-mcp@v0.2.1 jev-mcp

Codex (~/.codex/config.toml):

[mcp_servers.jev]
command = "uvx"
args = ["--from", "git+https://github.com/blakestone-x/jev-mcp@v0.2.1", "jev-mcp"]
env = { TYPESAFE_API_KEY = "..." }

Cursor or another MCP client:

{
  "mcpServers": {
    "jev": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/blakestone-x/jev-mcp@v0.2.1", "jev-mcp"],
      "env": { "TYPESAFE_API_KEY": "..." }
    }
  }
}

Replace ... with the key value. Passing it through the client environment keeps it out of tool arguments and request state.

The scripts/register.sh helper requires Bash 4+; do not run it with sh. Apply mode reads TYPESAFE_API_KEY from the environment and refuses to change client configuration when it is unset. --apply writes the plaintext key into ~/.codex/config.toml and the Claude Code user config. The key is briefly visible in the process list while claude mcp add runs because that command receives it as an argument. On Windows, use scripts/register.ps1; it restricts the resulting configuration files to the current user and keeps a .bak copy before rewriting an existing Codex configuration.

The install examples pin the public v0.2.1 tag. Omitting the tag tracks the repository's default branch instead.

Worked example

This call classifies one state containing five support-ticket texts against one label map. It returns one label for the combined state; send one request per ticket when you need an individual label for each ticket:

{
  "state": [
    "The password reset link expired before I could use it.",
    "I do not recognize the charge on my statement.",
    "My order arrived two days late.",
    "The export button shows a blank screen.",
    "Please add a dark theme."
  ],
  "labels": {
    "account_access": "Login, password, or sign-in problems.",
    "billing": "Charges, invoices, or payment questions.",
    "delivery": "Late, missing, or damaged deliveries.",
    "bug": "Unexpected product behavior.",
    "feedback": "Suggestions or general comments."
  },
  "question": "Which category best fits the combined state of these five support tickets?",
  "add_other": true
}

The response is an ordinary MCP structured result with a stable envelope:

{
  "ok": true,
  "model": "jev-latest",
  "answers": {
    "choice": "account_access",
    "confidence": 0.91,
    "probabilities": {
      "account_access": 0.91,
      "billing": 0.03,
      "delivery": 0.02,
      "bug": 0.02,
      "feedback": 0.01,
      "other": 0.01
    },
    "band": "act"
  },
  "usage": {
    "input_tokens": 420,
    "output_tokens": 0,
    "est_cost_usd": 0.00001764
  },
  "latency_ms": 130.0
}

Tools

tool	use it for	not for
`jev_ask`	Your own Choice, Score, and Noul question map	Text generation or numeric extraction
`jev_classify`	Selecting one label from a closed list	Open-ended writing or ranking without labels
`jev_score`	Placing state on an ordered rubric	Returning a number extracted from text
`jev_check`	Independent yes/no propositions	Treating a probability as proof
`jev_match`	Matching a query to candidates with abstention	Assuming the closest candidate is genuine
`jev_screen`	Filtering instruction-like or untrusted text	A security boundary or authorization decision
`jev_health`	Listing served models and measuring round-trip latency	Evaluating application content

Design principles

The key stays in the environment and never in the agent's context.
All policy thresholds live in one file: jev_mcp/questions.py.
Confidence is distribution concentration, not correctness.
Screening is a filter, not a security boundary.
Gate consequential decisions on the Score.
Order-ensemble turns disagreement into a cheap review signal.
Matching includes abstention through the exists Noul.

Profiles and recipes

examples/triage.questions.json and examples/route.questions.json are generic, complete jev_ask request examples. They contain a state object and a questions map in the wire shape accepted by jev_ask; replace state with your own data and send the whole object as the tool arguments. Jev intentionally does not load profiles for you.

import json

with open("examples/triage.questions.json", encoding="utf-8") as file:
    request = json.load(file)

result = await session.call_tool("jev_ask", request)

See RECIPES.md for comparison, reference-in-state, descriptions, batching, calibration, and order-ensemble patterns.

What we measured

The measurements below come from a field-service company's production data.

measurement	result
Clean labels at confidence 0.8 to 1.0	95% agreement
One-line label descriptions	81.0% agreement; 1,689 tokens/request
Rich label descriptions	84.5% agreement; 4,745 tokens/request
Reversing criteria order	32 of 200 choices flipped; flipped confidence averaged 0.42
Candidate matching	8 of 11 picks matched when a candidate existed; misses had low `exists`
Amount comparison	100% on 64 cases where displayed amounts differed
Past-date comparison	100% for “is it past”; 98% on a four-level overdue Score

Limits

The default serialized request budget is 120,000 characters for the state and questions sent to the service. Set JEV_MCP_MAX_REQUEST_CHARS to use a different positive limit. JEV_MCP_MAX_STATE_CHARS remains accepted as a compatibility alias for one release. For jev_match, the budget applies to the full candidate input and to each serialized candidate window. The service provider has not published rate limits. What we observed on one early-access key: small requests ran at 160 per second with flat latency and no rate-limit responses, while a sustained run of about 40 requests per second at 1,700 tokens each drew 429s after three minutes. Treat the limit as tokens per minute rather than requests per second, keep bulk jobs resumable, and back off for seconds on a 429, not milliseconds. This server's retry policy backs off from 1 second to 20 seconds and honors Retry-After. A Noul carries evidence strength, not confidence. Jev is early access: validate thresholds and outputs against your own data, and keep consequential actions behind your normal review controls.

jev_match accepts a window from 20 through 254 and up to 2,000 candidates by default. Set JEV_MCP_MATCH_MAX_CANDIDATES to change the candidate cap. For n candidates, the normal billed request count is ceil(n / window) + 1: one request per window plus one finalist-selection request. A single-window call may need only its initial request, and a call with no finalists may omit the extra request. exists is the maximum of the per-window values, so more windows can inflate it; inspect windows and exists_by_window too. The match deadline is 45 seconds by default and can be changed with JEV_MCP_MATCH_DEADLINE_S.

Set JEV_MCP_MODEL to select the model; it defaults to jev-latest. The timeout contract is: a single tool call can take up to about 30 seconds when the service is degraded; jev_classify(ensemble=true) can take about 60 seconds because it makes two sequential evaluations; jev_match can take up to its deadline. SDK attempts use an 8-second HTTP timeout and a 20-second retry budget.

License

MIT. See LICENSE.