Jev MCP
A small, dependency-light MCP server that gives any MCP client typed,
probabilistic decisions from Jev,
TypeSafe's System One model, through OpenRouter or TypeSafe directly.
Jev does not write text. You send it data plus typed questions and it returns
one calibrated answer per question: a choice among your options, a probability
for a yes/no, or a position on a scale you define, each with a confidence and
the full probability distribution. It answers in a single parallel pass, fast
and at a fraction of the cost of a chat model, and it cannot return an option
you did not offer.
This server exposes that as five MCP tools, validates every answer the provider
returns, never leaks your credential, and never retries a paid call.
Why use it
- Let your agent decide instead of guess. Routing, triage, classification,
claim checking and ranking become explicit, typed calls with probabilities
your workflow can act on or escalate.
- Cheap and fast. One paid inference call per tool invocation, regardless
of how many items or questions it carries.
- Provider agnostic. Use an OpenRouter key you already have, or a TypeSafe
key. Switch with one environment variable.
- Honest outputs. Answers are validated against the question you asked;
inconsistent or incomplete answers fail the call instead of being fixed up.
The unchanged provider response, including
usage.cost, is always returned.
- Safe by construction. Credentials live only in the server environment,
HTTPS is enforced, redirects are refused, request and response sizes and time
are bounded.
Quick start
1. Get an API key
- OpenRouter (default): create a key at openrouter.ai and
set
OPENROUTER_API_KEY. Jev is listed as
typesafe/jev-latest; the bare jev-latest id also works.
- TypeSafe: create a key at typesafe.ai and set
TYPESAFE_API_KEY together with JEV_PROVIDER=typesafe.
2. Install the server
Pick one:
Binary. Download the archive for your platform from
Releases (Linux, macOS
and Windows, amd64 and arm64), verify it against checksums.txt and put
jev-mcp on your PATH.
Container. Images are published for every tagged release:
docker pull ghcr.io/freepik-company/jev-mcp:latest
Go toolchain.
go install github.com/freepik-company/jev-mcp/cmd/jev-mcp@latest
3. Register it in your MCP client
The server speaks MCP over stdio and reads the credential from its environment.
Never put the key in tool arguments.
Claude Code
claude mcp add jev -e OPENROUTER_API_KEY="$OPENROUTER_API_KEY" -- jev-mcp
Claude Desktop, Cursor and other JSON-configured clients
{
"mcpServers": {
"jev": {
"command": "jev-mcp",
"env": { "OPENROUTER_API_KEY": "sk-or-..." }
}
}
}
Container instead of a binary (use -i, never -t; the key is inherited
from the client's environment):
{
"mcpServers": {
"jev": {
"command": "docker",
"args": ["run", "--rm", "-i", "-e", "OPENROUTER_API_KEY", "ghcr.io/freepik-company/jev-mcp:latest"]
}
}
}
For TypeSafe directly, add "JEV_PROVIDER": "typesafe" and TYPESAFE_API_KEY
instead of the OpenRouter key.
The server is also listed in the MCP Registry
as io.github.freepik-company/jev-mcp, so clients that browse the registry can
install it from there.
Configuration
| Variable | Default / purpose |
|---|
JEV_PROVIDER | openrouter or typesafe (default: openrouter) |
OPENROUTER_API_KEY | OpenRouter credential |
TYPESAFE_API_KEY | TypeSafe credential |
API_KEY | Overrides the selected provider's credential |
JEV_MODEL | jev-latest; overridable per tool call with model |
BASE_URL | Provider API root; /v1/systemone is appended |
Default roots: https://openrouter.ai/api and https://api.typesafe.ai.
BASE_URL must be HTTPS; plain HTTP is accepted on loopback only, for local
proxies and tests. Credentials belong in the server environment, never in tool
arguments.
| Tool | Input | Result |
|---|
decide | Shared state and named questions | Raw typed answers and provider metadata |
classify | items, categories, instructions | Category per item, confidence and probabilities |
verify | claims, evidence | supported, contradicted or insufficient_evidence per claim |
rerank | query, candidates, optional top_k | Descending relevance scores on a 0–4 rubric |
list_models | No arguments | Compatible model IDs and the configured default |
Items, claims, evidence and candidates are arrays of { "id": "unique-id", "text": "..." }
with 1–64 entries. Categories map category IDs to descriptions. The three task tools
accept an optional model, make one inference call, and return results plus the
unchanged provider response (including response.usage.cost when supplied).
Classification and verification preserve input order; ranking preserves it for ties.
top_k filters results after evaluating every candidate. Inputs are never truncated.
Verification uses only supplied evidence; its verdict is a model judgment, not a
proof or approval. No automatic acceptance thresholds are imposed. Model discovery
uses OpenRouter's decisions catalogue or TypeSafe's native catalogue, without inference.
Example: decide
{
"state": {"ticket": "Please refund the duplicate charge."},
"questions": {
"department": {
"type": "choice",
"instructions": "Which team should handle this ticket?",
"criteria": {"billing": "Payments and refunds", "technical": "Software defects"}
},
"refund": {"type": "noul", "instructions": "Is a refund requested?"},
"urgency": {
"type": "score",
"instructions": "How urgent is this ticket?",
"criteria": ["Routine", "Service blocked", "Active financial harm"]
}
}
}
choice selects a supplied option; noul returns P(true); score returns a
probability-weighted rubric index. Full provider output is preserved, including
score legends and usage.cost when available.
Example: classify
{
"instructions": "Route each support message to the right queue.",
"categories": {
"billing": "Charges, invoices and refunds",
"technical": "Bugs, errors and outages",
"other": "Anything else"
},
"items": [
{"id": "m1", "text": "I was charged twice this month."},
{"id": "m2", "text": "The export button does nothing."}
]
}
Returns one { "id", "category", "confidence", "probabilities" } per item, in
input order, plus the full provider response.
Limits and failure modes
Unknown input fields and incomplete or inconsistent answers fail the call.
Requests have a 30-second timeout, a 1 MiB input limit, and a 2 MiB response limit.
Paid calls are not automatically retried. Provider errors surface only their HTTP
status, never the response body, so a credential echoed by a provider cannot
reach the model. See the input and
output schemas for the complete contract.
Development
Only Docker is required:
make test
make image
make release
cmd/jev-mcp contains the entry point. internal/ separates configuration,
the System One client and answer validation, the task layer and the MCP protocol.
CI verifies builds and tests on every push and pull request; version tags publish
release archives, the container image on GHCR and the entry in the MCP Registry.
See CONTRIBUTING.md for the workflow and design principles,
SECURITY.md for reporting vulnerabilities and
CHANGELOG.md for release notes.
License
Apache License 2.0. Jev and System One are products of
TypeSafe AI; this project is an independent client and
is not affiliated with TypeSafe or OpenRouter.