Jev MCP

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.

Tools

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       # formatting, vet, race-enabled unit and integration tests
make image      # runtime image, tagged jev-mcp:local
make release    # archives and checksums for every platform in dist/

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.