Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@openrouter-jev-mcp Classify this error as code_defect, stale_test, or network_timeout."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Python decision gateway and Model Context Protocol (MCP) server for TypeSafe's Jev model through OpenRouter.
An independent community project, unaffiliated with TypeSafe or OpenRouter. The supported environment is Linux with Python 3.13; Windows is unsupported because diagnostic locking uses POSIX facilities.
Coding agents repeatedly encounter small, bounded questions that can benefit from a separate model judgement:
"Is this bug most likely:
code_defect / stale_test / network_timeout?"
│
▼
┌──────────────┐
│ Jev AI │ Typed decisions
│ Judge via │ Caller-defined questions
│ OpenRouter │ Probabilities
└──────┬───────┘
│
network_timeout (p = 0.94)
│
▼
Caller applies its own action policyTypeSafe AI's Jev returns typed, probabilistic decisions for software rather than free-form prose. TypeSafe documents three question types: Choice, Score and Noul. The probabilities above are illustrative; a judgement can be wrong and does not grant permission to act.
The gateway uses an OpenRouter key with the alpha Decisions endpoint (https://openrouter.ai/api/alpha/decisions) and the ~typesafe/jev-latest alias. Native TypeSafe keys and SDK routing are not supported. The endpoint is alpha; availability and its contract may change.
On 19 September 2026, OpenRouter listed Jev 1.13 at $0.042 per million input tokens and $0 for output, with approximately 260 ms median provider latency. These are provider figures, not gateway benchmarks or guarantees. Check the listing for current pricing; requests and retries can incur charges.
Related MCP server: askjev
This server runs over standard stdio and implements the MCP specification:
Tool | Jev Primitive | Use Case | Return Value |
| Noul | Yes / No propositions | Calibrated probability $P(\text{true}) \in [0.0, 1.0]$. |
| Choice | Categorizing state into a closed set of labels | Chosen label, full probability distribution, and confidence ($0.0–1.0$). |
| Score | Placing state along an ordered discrete rubric | Expected score index and confidence score. |
| Multi-Question | Evaluating an arbitrary dictionary of Choice, Score, and Noul questions simultaneously in one parallel pass | Dictionary of typed answers and token usage. |
| Diagnostics | Local configuration readiness; optional live probe | Readiness, configured model and connectivity status. Connectivity is unverified unless |
Failures return {"error": {"category": "…", "message": "…"}}. Treat an error as no judgement. See the setup guide for error categories, limits and configuration.
Linux with Python 3.13 (optionally managed with uv)
Clone the repository and install dependencies:
git clone https://github.com/ctmx/openrouter-jev-mcp.git
cd openrouter-jev-mcp
# Using uv (recommended):
uv venv --python 3.13 .venv
source .venv/bin/activate
uv pip install -e .
# Or standard pip:
python3.13 -m venv .venv
source .venv/bin/activate
pip install -e .Choose one installation method above. To configure a key, copy the environment template, restrict its permissions, then edit it locally:
cp .env.example .env
chmod 600 .env
# Edit .env with your actual key:
# OPENROUTER_API_KEY=sk-or-v1-...The gateway does not load .env automatically. In Bash, load only your own trusted file before running the example. This sends the example's state to OpenRouter and may incur a charge:
set -a
source .env
set +a
python examples/demo_openrouter_decisions.pyReplace the absolute paths and placeholder keys below. Keep credential-bearing settings private and out of version control. The agent host must supply the key to the server; a repository .env alone is insufficient.
Add the server to Claude Code using claude mcp add:
claude mcp add --scope user openrouter-jev-mcp \
-e OPENROUTER_API_KEY="sk-or-v1-your-key-here" \
-- /path/to/openrouter-jev-mcp/.venv/bin/python \
/path/to/openrouter-jev-mcp/src/server.pyAdd the server to your ~/.codex/config.toml:
[mcp_servers.openrouter_jev_mcp]
command = "/path/to/openrouter-jev-mcp/.venv/bin/python"
args = ["/path/to/openrouter-jev-mcp/src/server.py"]
env = { OPENROUTER_API_KEY = "sk-or-v1-your-key-here" }Launch Codex and use /mcp to check that the server starts and exposes all five tools. Tool discovery does not verify provider connectivity.
Add to your Cursor settings (~/.cursor/mcp.json):
{
"mcpServers": {
"openrouter-jev-mcp": {
"command": "/path/to/openrouter-jev-mcp/.venv/bin/python",
"args": ["/path/to/openrouter-jev-mcp/src/server.py"],
"env": {
"OPENROUTER_API_KEY": "sk-or-v1-your-key-here"
}
}
}
}Once configured, use Jev as an additional judgement during development. Your agent or application owns action permissions, thresholds and fallback behaviour; model judgements supplement tests and human review.
"Before modifying any code, inspect the failing test trace. Use
jev_classifyto evaluate whether the failure is most likely:code_defect,stale_test,flaky_environment, ormissing_config. Show me Jev's probabilities before continuing."
"Before running a command that deletes or moves files, use
jev_checkto assess whether it could delete persistent project data. Treat the result as advisory and follow the project's existing approval rules regardless of the score. If Jev returns an error, report that no judgement was available."
"Run the tests and inspect your git diff. Use
jev_evaluateto score whether the diff satisfies the requirement and whether unexpected files were altered."
You can also use the gateway directly in your own Python services. Set OPENROUTER_API_KEY first. Calls can raise JevGatewayError; handle that as an unavailable judgement. The output comments below are illustrative, not expected test results:
from src.gateway import JevGateway
with JevGateway() as jev:
# 1. Yes/No Check (Noul)
result = jev.check(
state="rm -rf /var/log/*",
proposition="Does this command delete files outside the current project?"
)
print(result["noul"]) # 0.98
# 2. Categorical Choice (Choice)
choice = jev.choice(
state="Connection timeout after 5000ms to redis:6379",
instructions="What subsystem failed?",
options={
"database": "Relational SQL database",
"cache": "Redis or Memcached key-value store",
"network": "DNS or proxy routing"
}
)
print(choice["choice"]) # "cache"
print(choice["confidence"]) # 1.0Validated answers: Malformed JSON, missing answers and invalid answer values produce structured errors. Valid structure does not guarantee a correct judgement.
Bounded retries: Up to three attempts for transient HTTP codes (408, 429, 502, 503, 504), connection errors and transport timeouts. Exponential backoff starts at 0.25 seconds; Retry-After seconds and HTTP-dates are honoured within the remaining request budget.
Request bounds: A 20-second network deadline covers attempts and backoff. Requests and responses are bounded, and at most eight requests may be in flight per gateway instance. Excess calls receive an immediate error.
Local diagnostics: Successful calls log state and answers by default to $JEV_LOG_DIR or ~/.local/state/jev-gateway, with owner-only permissions, a 20 MiB aggregate cap and 24-hour retention. Secret filtering is best effort and cannot detect every sensitive value.
Logging exclusions: RFC 6901 pointers such as logging_exclusions=["/state/customer"] omit specified fields from the diagnostic copy. They do not remove those fields from the state sent to OpenRouter. Remove confidential information before submitting it.
Logging failure handling: If local diagnostic logging fails, it emits one sanitised warning to stderr per logger and preserves decision processing. This does not turn provider errors into approvals.
See SETUP_GUIDE.md for detailed limits and privacy controls.
Run the offline test suite with credentials removed and diagnostic logs isolated in a temporary directory. Tests use synthetic keys and fake provider transports; they do not call OpenRouter:
# Run unit, resilience and stdio subprocess tests
test_logs=$(mktemp -d)
env -u OPENROUTER_API_KEY -u TYPESAFE_API_KEY JEV_LOG_DIR="$test_logs" \
.venv/bin/python -m unittest discover -s tests -v
# Syntax verification
.venv/bin/python -m compileall -q src tests examplesOffline tests do not verify current provider availability. Some restricted execution sandboxes can stall the MCP SDK's worker threads; see the verification notes. The native TypeSafe SDK example is legacy research material and is not part of the supported installation.
MIT © Chris (ctmx)
Evaluate a Noul proposition against string, object, or list state.
| Name | Required | Description | Default |
|---|---|---|---|
| state | Yes | ||
| proposition | Yes | ||
| logging_exclusions | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It says the tool 'evaluates' a proposition, but it does not state whether this is a read-only operation, whether there are side effects, whether authentication is needed, or what the output represents. The behavioral surface is mostly opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence with no filler or redundant phrasing. It is front-loaded with the core action and target. The main detraction is that it is concise to the point of omitting useful clarifying details, but it is appropriately sized for a simple check operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters, no annotations, and zero schema parameter coverage, the description is incomplete. It lacks proposition syntax, usage context, state format expectations, and any distinction from sibling evaluation tools. The presence of an output schema helps with return values, but it does not fill the input-semantics or usage-routing gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does add some meaning by specifying that 'state' can be a string, object, or list, which the schema leaves ambiguous. However, it does not clarify the syntax or meaning of 'proposition', the optional 'logging_exclusions' parameter, or the expected shape of the state values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Evaluate') and target ('a Noul proposition'), and it names the acceptable state types ('string, object, or list state'). This is clear enough at a high level, but it does not distinguish jev_check from the similar sibling 'jev_evaluate' or explain what 'Noul' means.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use jev_check versus jev_classify, jev_score, or jev_evaluate. The description implies a use case—checking a proposition against state—but provides no explicit context, exclusions, or alternative tool routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Choose one caller-defined label for string, object, or list state.
| Name | Required | Description | Default |
|---|---|---|---|
| state | Yes | ||
| options | Yes | ||
| question | Yes | ||
| logging_exclusions | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits. It does not state whether the operation is read-only, whether it has side effects, how it handles invalid states, or what the output format is. The minimal description leaves the agent guessing about the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief (one sentence), but this brevity is not effective conciseness—it is under-specification. It front-loads the core idea but omits critical details needed for correct usage. A good concise description would pack more actionable information into a few sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters, nested objects, no annotations, and an output schema that is not described in the definition. The description does not explain the purpose of each parameter, the expected output, or any edge cases. Given the complexity, the description is grossly inadequate for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining the parameters. It does not mention 'question', 'options', or 'logging_exclusions' at all. The only hint is 'caller-defined label', which loosely relates to 'options', but no parameter semantics are clarified. The description fails to aid in parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the core action ('choose one caller-defined label') and the input type ('string, object, or list state'), which gives a general sense of classification. However, it does not clarify what 'label' means, how it relates to 'options', or how it differs from the sibling tools (jev_check, jev_score, etc.). It is more than a tautology but remains vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention contexts where classification is preferred over scoring or evaluation, nor any exclusions or prerequisites. The agent is left to infer the appropriate usage from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Evaluate a named map of Noul, Choice, and Score questions.
| Name | Required | Description | Default |
|---|---|---|---|
| state | Yes | ||
| questions | Yes | ||
| logging_exclusions | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention side effects, state handling, permissions, output behavior, or what 'evaluate' actually does beyond the generic verb. This is a significant gap for a tool with required state and nested question structures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short, front-loaded sentence with no redundant wording. It is concise, but it is also under-specified, sacrificing necessary context for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value details are not strictly required, but the tool has two required parameters and nested objects. The description gives no guidance on state semantics, the structure of the question map, or logging exclusions, making it incomplete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It partially clarifies that 'questions' is a named map of specific question types, but the required 'state' parameter and 'logging_exclusions' are entirely undescribed, and the term 'Noul' is unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb, 'Evaluate,' and a specific resource, 'a named map of Noul, Choice, and Score questions.' This gives the agent a reasonable sense of the tool's scope. However, 'Evaluate' is generic and the sibling tool jev_score suggests a closely related operation, so the description does not clearly differentiate among the siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like jev_check, jev_classify, or jev_score. There are no conditions, examples, or exclusions, leaving the agent without enough context to select the right tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report OpenRouter configuration readiness; connectivity is unverified unless explicitly probed.
| Name | Required | Description | Default |
|---|---|---|---|
| verify | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It adds a meaningful, non-obvious trait: readiness reporting does not verify connectivity by default, and probing must be explicit. This is valuable transparency, though it does not mention side effects, permissions, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single well-structured sentence that front-loads the main purpose and then adds the essential caveat. Every word contributes meaning; there is no padding or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one optional boolean parameter) and the presence of an output schema, the description covers the core semantics and the most important behavioral nuance. It is slightly incomplete in not explicitly mapping the verify parameter to the probing behavior, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the single boolean parameter. It indirectly associates "verify" with probing connectivity via "unless explicitly probed," but it never explicitly states that setting verify=true performs the probe. For a single self-explanatory boolean, this is adequate but not strong.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: "Report OpenRouter configuration readiness." It is clear what the tool reports on, though it does not explicitly contrast itself with sibling tool jev_check, leaving some ambiguity about where the boundary between "health" and "check" lies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus siblings like jev_check, jev_classify, or jev_score. The caveat "connectivity is unverified unless explicitly probed" implies a conditional usage pattern, but it never states when to choose this tool or how to trigger the probe.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Score string, object, or list state against ordered caller-defined levels.
| Name | Required | Description | Default |
|---|---|---|---|
| state | Yes | ||
| levels | Yes | ||
| question | Yes | ||
| logging_exclusions | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Score' and gives no indication of whether the operation is read-only, how levels are interpreted, what output format is returned, or whether any side effects occur. This is a significant gap for a tool with no annotation safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is compact and contains no filler, but this is under-specification rather than conciseness. It omits essential usage and behavioral information, so brevity is achieved at the expense of usefulness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although an output schema exists, the description is too sparse to enable correct invocation. It does not explain how levels map to scores, what 'question' is for, or how this tool relates to sibling tools like jev_check or jev_classify. For a 4-parameter tool with zero schema descriptions, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clarifies 'state' accepts string/object/list and 'levels' are ordered and caller-defined, but it leaves the required 'question' parameter and the optional 'logging_exclusions' entirely unexplained. Nearly half the parameters are undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Score') and identifies the input types (string, object, list) plus the scoring rubric (ordered caller-defined levels). This is clear, but it does not distinguish the tool from siblings like jev_evaluate, which could plausibly perform a similar action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives. It does not mention criteria, exclusions, or contexts where other sibling tools would be more appropriate, leaving the agent to rely on the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0jev_checkjev_classifyjev_evaluatejev_healthjev_scoreScored across 5 tools
Each tool has a distinct evaluation purpose: single check, classification, scoring, batch evaluation, and health reporting. The only mild overlap is between jev_check and jev_evaluate, since evaluate can contain Noul questions, but the singular versus map distinction keeps them separable.
All tools share the jev_ prefix and use lowercase snake_case, creating a clear family resemblance. The main inconsistency is that four tools are verb-based (check, classify, score, evaluate) while jev_health is a noun, but the pattern remains predictable.
Five tools is a well-scoped set for an evaluation-oriented server: single operations plus a batch operation plus health. Each tool has a distinct role without unnecessary redundancy.
The tool surface covers the core evaluation lifecycle: primitive checks, categorical classification, ordered scoring, batched evaluation of mixed question types, and health/configuration readiness. No significant dead ends or missing core operations are apparent for the stated domain.
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
MCP-first toolbox for agents: KV storage, auth, queue, and utility tools. Free in early access.
Calibrated world model for AI agents. 40 tools: world state, markets, trading. Kalshi + Polymarket.
Verified, pay-per-use API tools for AI agents through one authenticated connection.
