Jev MCP

A standalone stdio MCP adapter for sending a context, question, and named choices to Jev System One. It exposes one tool, jev_decide, and returns Jev's selected choice, confidence, and per-choice probabilities as scores.

Requirements

• Node.js 20 or newer

• A Jev API key for actual decisions

• An MCP host that can launch a stdio server

Related MCP server: jevcore-mcp

Configure

Copy .env.example to .env and set JEV_API_KEY. JEV_API_BASE_URL is the API origin, defaults to https://api.typesafe.ai, and can be overridden for another supported environment. The adapter posts to /v1/systemone.

The adapter sends model: "jev-latest", the supplied context as state, and the question and choices in a choice question. It authenticates with a Bearer token. Jev's response answer is mapped from answers.decision to { choice, confidence, scores }, with probabilities exposed as scores.

When launched by the tunnel client, the child inherits JEV_API_KEY and, optionally, JEV_API_BASE_URL from the tunnel client's environment. The server reads these variables from its process environment; it does not load .env files itself.

Install and run

npm ci
npm run typecheck
npm test
npm run build
JEV_API_KEY=your-key /home/ms/.volta/bin/node dist/server.js

The Linux host must have Volta installed for the ms account, with Node.js 20 or newer available through /home/ms/.volta/bin/node. This stable shim selects the account's configured Node.js version without hard-coding Volta's version-specific runtime path. The server communicates only over stdin/stdout; diagnostics go to stderr.

Secure Tunnel client

The tunnel client owns the connection and launches this stdio process when needed. Follow the OpenAI Secure MCP Tunnel Client installation and authentication instructions, then initialize a stdio profile. A typical local registration uses:

/home/ms/packages/jev-mcp/bin/tunnel-client init --sample sample_mcp_stdio_local --profile jev-mcp --profile-dir /home/ms/packages/jev-mcp/tunnel-profile --tunnel-id <tunnel-id> \
  --mcp-command "/home/ms/.volta/bin/node /home/ms/packages/jev-mcp/dist/server.js"
/home/ms/packages/jev-mcp/bin/tunnel-client doctor --profile jev-mcp --profile-dir /home/ms/packages/jev-mcp/tunnel-profile
/home/ms/packages/jev-mcp/bin/tunnel-client run --profile jev-mcp --profile-dir /home/ms/packages/jev-mcp/tunnel-profile

Copy .env.example to .env and set JEV_API_KEY, CONTROL_PLANE_API_KEY, and TUNNEL_CLIENT_PROFILE_DIR. Reference CONTROL_PLANE_API_KEY from the profile configuration using the sample's env: syntax. The tunnel client process inherits JEV_API_KEY, so its stdio child can authenticate to Jev. Keep .env private and do not commit it.

deploy/jev-mcp-tunnel.service is a user service for the ms account and uses the profile under this repository. The unit sets VOLTA_HOME=/home/ms/.volta and places /home/ms/.volta/bin on PATH so the tunnel process and its stdio child can resolve Volta shims. The profile must already be initialized and authenticated. Install and start it with:

mkdir -p /home/ms/.config/systemd/user
install -m 0644 deploy/jev-mcp-tunnel.service /home/ms/.config/systemd/user/jev-mcp-tunnel.service
systemctl --user daemon-reload
systemctl --user enable --now jev-mcp-tunnel.service

For the service to keep running after ms logs out, enable lingering once with loginctl enable-linger ms.

Development

npm run lint
npm run typecheck
npm test
npm run build

Tests use a stubbed Jev HTTP response and verify the stdio MCP handshake without requiring an API key or the Jev service.