OpenJEV README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the OpenJEV listing page.
openjev-mcp
Give your agent decisions, not paragraphs. An MCP server that turns "classify this", "how severe is this", and "is this urgent?" into typed answers with calibrated probabilities that your code can branch on.
A real call: one ticket, three questions, one request. Reproduce it with
OPENJEV_API_KEY=... npm run demo (demo/run.mjs).
See an agent use it: recorded transcripts of DeepSeek Harness triaging an electric co-op's help desk, from one member complaint to a morning's queue.
It's powered by Jev, TypeSafe's System One model, through the public OpenJEV API. You send one context and any number of independent questions in one call, and the server checks the request locally, retries transient failures, and validates every answer before your agent sees it.
What people use it for
| Use case | Tool | Example question |
|---|---|---|
| Support triage | jev_ask | Which team owns this ticket, and is it urgent? |
| Content moderation | jev_score | How harmful is this message: none, mild, serious? |
| Prompt-injection screening | jev_noul | Is this input trying to override instructions? |
| Agent routing | jev_choice | Which sub-agent or workflow should handle this request? |
| PR / change risk | jev_score | How risky is this diff to deploy on a Friday? |
| Lead qualification | jev_ask | Company size bucket? Buying intent? Budget mentioned? |
| LLM-as-judge evals | jev_score | Does this answer fully address the question? |
| Free text to a known value | jev_choice | Which of our 200 product SKUs is this customer describing? |
| Queue triage and backfills | jev_batch | For each of these 80 open tickets: which category, and is anyone in danger? |
The rule of thumb: if ordinary code can't express the decision but your code needs to act on the result, it's a Jev question.
Quick start
You need Node.js 20+ and an API key from https://openjev.sh/dashboard.
Claude Code
Cursor, VS Code: use the install buttons above, then paste your key.
Claude Desktop, Windsurf, Cline, and any other client that uses the mcpServers
shape:
Then ask your agent something like "Use jev_ask to route this ticket and tell me if it's urgent: …".
If calls fail with a missing key, the key is in the wrong place. Each client reads it from a different spot, and some spots silently do nothing: see Where the API key goes.
Verify the key
It spends one small judgment and exits 0. A rejected key exits 1 with the reason;
a missing key exits 2. Running the server by hand without --check proves nothing:
it waits silently for a client on stdin.
DeepSeek Harness
This server is developed and verified against
DeepSeek Harness. Add one entry to
the profile patch layer at ~/.dsh/profiles/<profile>/cordis.patch.yml:
Two fields are deliberate. The key is named in env because the harness hands MCP
children a scrubbed environment with credential-shaped names removed. The timeout is
raised because the server's own worst case is ~120 s (see
docs/production.md), and the 60 s default would abort the third
attempt.
Other ways to install
- Global install, for a pinned version and a faster start than
npx:npm install -g openjev-mcp, then use"command": "openjev-mcp"with noargs. - From a checkout:
npm ci && npm run build, then"command": "node"and"args": ["/absolute/path/to/openjev-mcp/dist/index.js"].
Passing --env-file=... through args does not work with openjev-mcp or npx:
Node validates the flag when it appears after the script name but does not load it, so
the server would start without a key. To keep the key in a file, use command: node
with args: ["--env-file=/path/to/.env", "/path/to/dist/index.js"].
The server exits immediately if the key is missing or a setting cannot be parsed,
writing the reason to stderr (exit code 2). stdout carries JSON-RPC and nothing else.
Why this is a server and not a direct API call
OPENJEV_API_KEY belongs in a server environment. An MCP client runs on someone's
machine, so the key lives here, in this process's environment, and never reaches the
model, the client, or a tool argument. The server also keeps the request rules and the
retry policy in one place instead of in every prompt.
Environment variables
| Variable | Default | Meaning |
|---|---|---|
OPENJEV_API_KEY | — | Required. Bearer token for the API. |
OPENJEV_BASE_URL | https://api.openjev.sh | API origin, for a proxy or a test double. |
OPENJEV_TIMEOUT_MS | 30000 | Per-attempt timeout, 1000–600000. |
OPENJEV_MAX_RETRIES | 2 | Retries after the first attempt, 0–10. |
OPENJEV_MODEL | unset | Model alias sent when a call does not name one. Unset uses the service default, openjev. |
OPENJEV_BATCH_CONCURRENCY | 4 | Requests one jev_batch call keeps in flight, 1–16. Set it from the rate your key is assigned. |
Tools
| Tool | Use it when | Answer |
|---|---|---|
jev_ask | Several judgments share one context. One call, one price, one latency. | answers keyed by your question ids |
jev_choice | The answer is one of a set you define — a category, a route, a selection. | one option + probabilities + confidence |
jev_score | The answer is a position on an ordered scale — degree, severity, intensity. | score + legend + probabilities + confidence |
jev_noul | The answer is yes or no, and the probability is what matters. | a value in 0–1 |
jev_batch | The same questions apply to many records — a queue, a backlog, a page of results. | answers keyed by your item ids, plus per-item errors |
Every tool judges a state (string, object, or array; jev_batch takes one per item)
against instructions, and accepts an optional model — see the descriptions in
tools/list, which carry the design guidance an agent needs to pick between primitives.
jev_ask — several independent questions, one call
jev_score — an ordered scale you define
jev_noul — a probability, no confidence field
Read it as probability, not intensity: near 1 yes, near 0 no, near 0.5 uncertain. A confident no is near 0.
jev_batch — the same questions across many items
jev_ask puts many questions to one state; jev_batch puts one set of questions to up
to 100 states. An electric co-op's help desk, triaging this morning's member messages:
Your code takes it from there: page the line crew for a high hazard, and queue the rest
by category, at thresholds you calibrated on your own tickets.
Give each item its record's own id so results map back without counting positions;
without ids, items are labelled "0", "1", and so on. Each item is its own request, so
it costs what a jev_ask with the same questions costs: a batch saves the agent turns,
not tokens.
An item that fails does not sink the rest. It lands in errors, keyed by its id, and the
batch carries on:
When going on would only spend calls on a failure that repeats, the batch stops, keeps
every answer it has, and says why in stopped. The items it never sent are listed in
not_sent; send them in a later call, after retry_after_ms when it is given:
A batch that answers nothing is a tool error, like any other failed call.
What the server adds to a bare HTTP call
Requests are checked before they are sent. Bad input otherwise costs a round trip and returns less than the local check does. Every problem is reported with its path:
The rules enforced are the documented ones: non-empty state and questions; the
255-option ceiling and 2-option floor for choice; the 10-level ceiling for score;
criterion descriptions that are strings, objects, arrays, or null; and noul criteria
limited to true and false. An array of option names is accepted as shorthand for
descriptions-free options.
One non-blocking hint. A choice with no fallback option gets a hints entry rather
than an error — the judgment is still made, and the caller learns to add other or none.
Transient failures are retried, within budget. 429 (honoring Retry-After), 5xx,
timeouts, and network errors are retried with exponential backoff and jitter, up to
OPENJEV_MAX_RETRIES. A Retry-After longer than 15 seconds is surfaced, not slept
through, so a tool call cannot hang for minutes. Retries stop early on 401 and 422,
which cannot succeed on a repeat.
Batches are paced, and stop when going on cannot help. jev_batch keeps
OPENJEV_BATCH_CONCURRENCY requests in flight (4 by default). A 429 on any of them
pauses new requests for the interval the service asked for and halves the concurrency for
the rest of the call, as the OpenJEV docs direct. The batch stops early on a rejected key,
on a rate limit that one call cannot wait out, and after three items fail in a row. It is
bounded by the same worst case as a single call (~120 s by default): items still in flight
then are cancelled and reported, so the client timeout that covers one call covers a batch.
When the client supplies a progress token, the server reports progress after each item.
Responses are validated against the contract. A 2xx body that is not the documented
shape — no answers, an unknown answer type, a missing probabilities/confidence on a
choice or score, a noul outside 0–1, a question left unanswered — becomes a
malformed_response error instead of a judgment the caller might mistake for real.
Failures arrive as tool errors with a next step, machine-readable and human-readable:
Codes: missing_api_key, auth, invalid_request, rate_limited, unavailable,
timeout, network, aborted, malformed_response.
What it deliberately does not do
- No thresholds, no routing policy.
confidenceis passed through untouched. It summarizes how concentrated the distribution is — it is not the probability of being correct — so the threshold that decides "act" versus "send to a person" belongs to your application, calibrated on your own labeled examples. - No question chaining. Every question in a call is evaluated independently against the same state. The server does not fake a sequence: make a second call when an answer decides what to fetch or ask next.
- No images, audio, or files. The API accepts text and JSON only, so neither does the server.
- No HTTP transport. stdio only. A networked deployment needs authentication of its own, and that is a different design.
- No key in the client. Tool arguments cannot carry credentials.
Production setup
The shipped defaults suit a single operator. For a team, a regulated workload, or any
deployment with an on-call rotation, follow docs/production.md.
The operational requirements in summary:
- Credentials. The key is held in the machine's environment, mode
600, and never in a repository. Rotation requires updating the file and restarting the client: the harness reads its environment at startup, so a file change alone has no effect. Setup and placement: Where the API key goes. - Client call timeout above ~120 s. That is the server's worst case — 3 attempts × 30 s
plus two Retry-After waits of up to 15 s. A 60 s client timeout aborts a retry that was still in progress.
A
jev_batchcall is bounded by the same figure. - Batch rather than fan out. Rate limits apply per key and are shared by every process
using it. One
jev_askcarrying five questions is one request; five parallel calls are five. For many records, onejev_batchpaces its requests where parallel calls would not. stateleaves the machine. It is processed by TypeSafe's hosted service, so treat it as third-party disclosure and submit only what the judgment requires. The server's own logs never contain it.openjev-mcp --checkis the readiness probe: exit0healthy,1key rejected,2misconfigured. It costs one small call.
The guide also carries the rotation runbook, the latency budget arithmetic, a failure table covering every error code, the upgrade and rollback procedure, and an explicit list of what is not built.
Development
The full test suite runs against the built output, with no network and no API key: a mock OpenJEV
drives the client and tool paths, an in-memory transport pair exercises the MCP protocol,
and one test spawns dist/index.js and speaks raw JSON-RPC over stdio to prove stdout
carries nothing but the protocol.
Contributions are welcome: see CONTRIBUTING.md.
Links
- OpenJEV docs: https://openjev.sh/docs · plain text: https://openjev.sh/llm.txt
- TypeSafe, on the primitives: https://docs.typesafe.ai/primitives
License
MIT — see LICENSE.