jev-mcp
jev-mcp exposes four read-only MCP tools that consult TypeSafe AI Jev for bounded, advisory probabilistic second opinions—it never edits files, runs commands, or overrides the host model.
jev_decide— choose among 2–255 explicit alternatives from a state/context plus one atomic question.jev_route— pick a routing path from 2–255 candidate tools, subsystems, or workflows given an objective.jev_risk_score— get an advisory low/medium/high/critical risk signal for a proposed action and its context.jev_gate— evaluate an atomic yes/no statement against a probability threshold (default 0.8, range 0–1).Each tool takes minimal
state(string, object, or array) and accepts an optionalmodeloverride for the Jev model.Results are advisory only: read-only, stdio transport, no destructive actions, and final decisions stay with the active host model.
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., "@jev-mcp should we retry, rollback, or change strategy?"
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.
jev-mcp
Unofficial, community-maintained MCP server for TypeSafe AI Jev.
简体中文 · One-click install · Quick start · Examples · Security · FAQ
jev-mcp exposes TypeSafe AI's Jev decision model as four conservative,
read-only MCP tools for bounded probabilistic decisions.
It is intentionally designed as a second-opinion layer, not as a replacement for the active coding/reasoning model.
This project is not affiliated with, endorsed by, sponsored by, or an official product of TypeSafe AI or OpenAI.
Why this exists
Strong coding agents are good at open-ended reasoning, code generation, debugging, and repository-wide analysis. Jev is useful for a different class of problem: small, explicit decisions that benefit from a structured probability signal.
Typical examples:
retry vs rollback vs change strategy;
route to one of several known tools or subsystems;
estimate low / medium / high / critical change risk;
evaluate a yes/no gate against a threshold;
repeat the same bounded decision many times in an automated workflow.
The design rule is simple:
deterministic evidence
>
host-model repository-aware reasoning
>
Jev probabilistic adviceA Jev result is advisory. It is never proof, never ground truth, and never authorization for destructive or irreversible work.
Related MCP server: jev_mcp
Architecture
flowchart LR
U[User] --> H[Active host model / MCP client]
E[Tests · compiler · runtime · static analysis] -->|highest-priority evidence| H
H -->|stdio MCP| M[jev-mcp]
M -->|HTTPS + Bearer token| J[TypeSafe AI Jev API]
J -->|probabilistic advisory result| M
M -->|structured tool result| H
H --> O[Final decision / action]The API key stays in the local process environment or a gitignored .env file.
It is not placed in the MCP client configuration.
Privacy boundary: anything placed in a tool's state is sent to the
configured TypeSafe API endpoint. Send only the minimum necessary, preferably
redacted state. See Security and privacy model.
Tool surface
Tool | Use it for | Do not use it for |
| Choosing among 2–255 explicit alternatives | Open-ended design or coding |
| Routing among known tools/subsystems/workflows | Switching the user's selected model |
| Advisory low/medium/high/critical risk signal | Replacing tests or review |
| Yes/no probability against a threshold | Authorizing destructive actions |
All four tools are declared read-only. They do not edit files, execute shell commands, deploy infrastructure, or change the model selected by the user.
Successful responses include local metadata similar to:
{
"jev_mcp_advisory": {
"authority": "secondary_advisory",
"finalDecisionBy": "active_host_model",
"deterministicEvidenceOverrides": true,
"doNotTreatProbabilityAsFact": true
}
}That metadata is added by this MCP server; it is not Jev model output.
One-command install
Requires Node.js 20+, npm, Git, a supported MCP client, and a TypeSafe API key with applicable access/credits. Installation downloads the runtime and dependencies; tool calls require access to the configured TypeSafe endpoint. This repository is not published as an npm package.
No manual MCP JSON/TOML editing is required. The bootstrap installs a shared
runtime at ~/.jev-mcp/runtime, asks for the TypeSafe key with hidden input,
and configures the selected client.
macOS / Linux:
# Codex
curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- codex
# Claude Code
curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- claude-code
# Kimi Code
curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- kimi
# ZCode
curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- zcode
# Cursor
curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- cursor
# Gemini CLI
curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bash -s -- geminiWindows PowerShell (replace codex with another target as needed):
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.ps1))) -Target codexTo configure every detected user-level client:
curl -fsSL https://raw.githubusercontent.com/Afloat16/jev-mcp/v0.5.0/scripts/install.sh | bashThe key is stored only in ~/.jev-mcp/.env; client MCP configs contain no
TypeSafe credential. Existing JSON configs are backed up before modification.
Supported targets: Codex, Claude Code, Kimi Code, ZCode, Cursor, Gemini CLI,
Windsurf-compatible config, generic .agents/mcp.json, and project-scoped
VS Code/Copilot Agent configuration.
See Installation for Windows commands, updates,
uninstall, --skip-key, and advanced controls.
Source install
For contributors or users who prefer a local checkout:
git clone https://github.com/Afloat16/jev-mcp.git
cd jev-mcp
./setup.shWindows PowerShell:
git clone https://github.com/Afloat16/jev-mcp.git
cd jev-mcp
./setup.ps1Codex configuration
Add this to ~/.codex/config.toml and replace the path:
[mcp_servers.jev]
command = "node"
args = ["/ABSOLUTE/PATH/TO/jev-mcp/dist/index.js"]Restart the MCP host or start a new session after configuration changes.
For users who explicitly want a conservative cross-project Codex policy, merge:
codex/AGENTS.jev-conservative.mdinto your own ~/.codex/AGENTS.md.
Do not copy unrelated existing instructions away.
Which integration should I use?
Situation | Recommended approach |
Everyday interactive coding | Strong host model alone, or TypeSafe's agent skill |
Learning Jev concepts / patterns | TypeSafe agent skill |
Stable callable decision tools |
|
CI / agent orchestration |
|
High-volume application logic | Direct SDK/API integration is often the cleanest |
Need Jev to replace tests/compiler | Do not use Jev for that |
The MCP is most useful when the tool boundary itself matters: repeatability, structured output, orchestration, explicit thresholds, or shared agent workflows.
Configuration
Variable | Required | Default | Description |
| yes | — | TypeSafe credential |
| no |
| Jev model override |
| no |
| API base URL |
| no |
| Request timeout, 250–120000 ms |
| no | auto | Explicit env file; otherwise project |
Existing process environment variables override file values. Without JEV_ENV_FILE, a checkout-local .env is loaded before the installer-managed ~/.jev-mcp/.env.
Secret-handling rules
Never commit
.env.Never put API keys in
README,AGENTS.md, MCP config, examples, issues, screenshots, or CI logs.If a key is ever pasted into a shared surface, rotate/revoke it.
Run
npm run secrets:checkbefore publishing changes.
The bundled scanner is a guardrail, not a complete DLP system.
Examples
See examples/README.md for redacted examples covering:
ambiguous CI failure routing;
change-risk assessment;
retry / rollback / escalate decisions;
yes/no gates with explicit thresholds.
All examples intentionally use synthetic data and placeholders.
First tool call
After installation, restart the selected client or open a new session so it can
discover the tools. When uncertainty remains after inspecting a failure, supply
a small, redacted state to jev_decide. For example, these are its input
arguments in MCP Inspector or another MCP client:
{
"state": {
"failure": "A CI step intermittently fails while downloading a public test fixture.",
"http_status": 503,
"local_test": "passes with the fixture already present",
"attempts": 1
},
"question": "Which reversible handling path should be checked next?",
"options": [
{
"id": "retry",
"description": "Retry the download once with a bounded timeout"
},
{
"id": "inspect",
"description": "Inspect the fixture host and CI network logs first"
},
{
"id": "review",
"description": "Stop automatic retries and request review"
}
]
}This is synthetic input, not a recorded provider response. A live call sends
state to TypeSafe and may consume credits. Inspect the returned advisory
alongside the logs; the host model chooses the next step.
Local verification
No TypeSafe API call:
npm run doctor
npm run checkInteractive MCP inspection:
npm run inspectA live tool invocation in MCP Inspector uses your own TypeSafe account and may consume provider credits.
Project status
Item | Status |
Interface | 4 read-only MCP tools |
Transport | local stdio |
Node.js | 20+ |
License | MIT |
npm publishing | intentionally disabled |
API dependency | TypeSafe-hosted System One API |
Stability | pre-1.0; behavior may evolve |
The project follows semantic versioning in spirit. Stable one-click installs are pinned to the current release tag (v0.5.0) rather than main; users who intentionally want development builds can set JEV_MCP_GIT_REF=main. While the project remains below 1.0.0, minor releases may refine tool schemas or behavior. Breaking changes
should be documented in CHANGELOG.md and migration notes.
Documentation
Contributing
Focused issues and pull requests are welcome. Please read CONTRIBUTING.md first and run:
npm run checkbefore opening a PR.
Security-sensitive reports should follow SECURITY.md, not public issue comments.
License
MIT. See LICENSE.
The license covers this repository's code only. Third-party services, names, APIs, trademarks, pricing, and availability remain subject to their respective owners. See NOTICE.
References
TypeSafe AI documentation: https://docs.typesafe.ai/
TypeSafe AI — Introducing System One Models & Jev: https://typesafe.ai/blog/introducing-system-one-models-and-jev
Model Context Protocol TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk
Related projects
See the Afloat16 project guide for robotics diagnostics, model interfaces, 3D geometry, research and engineering workflows.
Available Tools
4 toolsjev_decideJev DecideARead-only
Use as an independent second opinion only after inspecting enough context when a bounded decision has 2-255 explicit alternatives and genuine uncertainty remains. The active host model keeps final authority; do not mechanically follow Jev or use it for open-ended coding/prose.
Inputs: state (required), options (required), question (required), model.
jev_gateJev GateARead-only
Use as an advisory second opinion for an atomic yes/no gate when a probability threshold would materially change the next action. A passed gate is not authorization for destructive, irreversible, production, security, or data-loss-sensitive actions.
Inputs: state (required), statement (required), model, threshold.
jev_risk_scoreJev Risk ScoreARead-only
Use as an advisory second opinion for consequential or ambiguous-risk changes after inspecting relevant context. Returns low/medium/high/critical risk. It is never authorization to proceed and never overrides tests, deterministic evidence, primary-model reasoning, or review.
Inputs: state (required), model, question.
jev_routeJev RouteBRead-only
Use as a second opinion for uncertain routing among a fixed set of tools, subsystems, workstreams, or handling paths only when deterministic evidence does not already decide the route. Never changes the user-selected host model.
Inputs: state (required), objective (required), candidates (required), model.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct decision scope: jev_gate handles atomic yes/no gates, jev_decide handles bounded multi-alternative decisions, jev_route handles routing among fixed paths, and jev_risk_score produces risk levels. The descriptions reinforce these boundaries, so an agent can reliably select the right tool without overlap.
All tools share the jev_ prefix and use snake_case, which is predictable and readable. However, the suffixes mix verbs and nouns (decide, route vs. gate, risk_score), so the pattern is mostly rather than perfectly uniform.
Four tools is well-scoped for a focused advisory second-opinion server. Each tool covers a distinct decision category, and none appears redundant or trivial.
The surface covers the main advisory decision types: binary gate, bounded choice, routing, and risk scoring. Minor gaps exist around explaining or calibrating second opinions, but agents can work around them within the stated domain.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Read-only MCP tools for AI agent discovery, structured resources, and NIULAI information.
Patterns for designing and reviewing AI skills, agents, and multi-agent workflows. Find guidance on context economy, delegation, verification, and tool design; inspect claims, worked examples, maturity labels, and source references. Five read-only tools let agents discover relevant patterns, compare concise cards, read specific sections, and explore relationships. Hosted Streamable HTTP at https://agentic-atlas.dev/mcp/ — no installation, account, or API key required. Browse the atlas at https://agentic-atlas.dev/.
Remote MCP utilities for agents: structured data, commerce checks, and x402 paid API discovery.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables MCP hosts to query Jev's typed decision model—yes/no, choice, and score—with calibrated probabilities, while defaulting to an offline mock and disclosing all egress unless explicitly enabled.107Apache 2.0
- AlicenseNot gradedqualityCmaintenanceProvides MCP tools that wrap Jev's finite typed judgments to give agents a semantic decision-control layer for task routing, pre-execution risk gating, and completion verification, keeping final execution authority in code.MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server that exposes eleven typed decision tools—check, choose, score, judge, route, triage, guard, grep, rank, compact, and ask—so agents can make fast, branchable yes/no, option-pick, score, and filtering decisions on text via TypeSafe's Jev model.10 npm2MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP-capable agents to run TypeSafe's Jev judgment model as typed yes/no, choice, and score tools, with calibrated probabilities, confidence thresholds, escalation for uncertain or non-judgment tasks, and an optional action gate that fails open.1MIT