Jev Decision MCP

A local stdio MCP server exposing one tool, jev_decide, for typed decisions through the official TypeSafe API. Written in TypeScript with the official MCP and TypeSafe SDKs.

Independent community project; not affiliated with TypeSafe. Licensed under MIT.

Batch independent questions over the same context in one call. Answers retain their question IDs. The MCP returns judgments and token usage; the caller owns thresholds, escalation, and action execution.

Requirements

• Node.js 22 or newer, with npm available on your PATH.
• An MCP client that supports local stdio servers.
• An API key from TypeSafe Console. Use an official TypeSafe key; OpenRouter and third-party gateway keys are not supported.

Install from npm

The npm package includes the built server. npx downloads it on first use and runs it without cloning or building:

npx -y jev-decision-mcp@0.1.3

Add the following to your MCP client's configuration, replacing YOUR_TYPESAFE_API_KEY with your key. For clients that use mcpServers JSON:

{
  "mcpServers": {
    "jev": {
      "command": "npx",
      "args": ["-y", "jev-decision-mcp@0.1.3"],
      "env": {
        "TYPESAFE_API_KEY": "YOUR_TYPESAFE_API_KEY"
      }
    }
  }
}

Alternatively, set TYPESAFE_API_KEY in the environment that launches your client and omit env if the client forwards that variable. Restart or reload your client's MCP servers after saving the configuration; the tool appears as jev_decide.

If the host cannot resolve npx, use its platform-specific launcher or absolute path as documented by that host. GUI applications may have a different PATH from your terminal.

The server communicates over stdio; starting it in a terminal waits for an MCP client rather than opening a web page. The npm installation does not read a .env from the caller's working directory.

To install the executable globally instead:

npm install -g jev-decision-mcp@0.1.3

Then use "command": "jev-decision-mcp" with no arguments in your MCP client, and supply the same API key.

Install via Glama

Open Jev Decision MCP on Glama to view its README, tool schema, and source. For local installation, use the npm configuration above, or follow the listing's GitHub Repository link to download or clone the source and build it below. Glama lists this as a local stdio server; the listing URL is not an MCP connection endpoint.

Connect to Codex

For the npm package, merge this into your Codex config.toml:

[mcp_servers.jev]
command = "npx"
args = ["-y", "jev-decision-mcp@0.1.3"]
env_vars = ["TYPESAFE_API_KEY"]
tool_timeout_sec = 45

Set TYPESAFE_API_KEY in the environment that launches Codex; env_vars forwards its existing value to the server. Keep the host tool timeout above JEV_TIMEOUT_MS / 1000. See official Codex MCP configuration.

Build from source

Clone the repository, install its dependencies, and compile the server:

git clone https://github.com/amidabuddha/jev-decision-mcp.git
cd jev-decision-mcp
npm ci
npm run build

You can also download the repository with Code → Download ZIP on GitHub, extract it, and run npm ci and npm run build in the extracted directory.

Copy .env.example to .env in that directory and set TYPESAFE_API_KEY, or supply the key through your MCP client's environment. The source build reads this .env regardless of its working directory; existing environment variables take precedence. Restart the server after changing it. .env is excluded from Git.

Configure your MCP client to run the built entry point:

{
  "mcpServers": {
    "jev": {
      "command": "node",
      "args": ["/absolute/path/to/jev-decision-mcp/dist/index.js"]
    }
  }
}

Replace the placeholder with your checkout's absolute path. Windows paths can use forward slashes, for example C:/projects/jev-decision-mcp/dist/index.js. If node is not on the client's PATH, use the absolute path to your Node executable.

For Codex, use the same command and args in the TOML example above. Keep env_vars only if you supply the key through Codex's environment instead of .env.

To verify your build, run npm run check (type checking and tests with mocked API responses; no TypeSafe calls). Use npm run dev for local development and rebuild with npm run build after source changes before restarting your MCP client.

Configuration

Set these variables in your MCP client's server environment, or in .env for a source build:

Keep your client's tool timeout above JEV_TIMEOUT_MS / 1000 seconds. jev-latest follows TypeSafe model updates; set a specific supported model version for repeatable evaluations.

The server starts without a key so a client can discover the tool, but decision calls then return MISSING_API_KEY. State and questions are sent to the official TypeSafe API and may incur API charges. TYPESAFE_BASE_URL does not override the API endpoint. The server does not persist inputs or decisions, and upstream error bodies are not exposed.

Call the tool

Call jev_decide with the JSON in examples/decision.json. It combines a team choice, a refund yes/no judgment, and an urgency score. Smaller example:

{
  "state": { "request": "Please refund the duplicate charge." },
  "questions": {
    "route": {
      "type": "choice",
      "instructions": "Which team should handle `request`?",
      "criteria": {
        "billing": "Charges, invoices, refunds",
        "technical": "Broken software or integrations",
        "other": "Neither billing nor technical"
      }
    }
  }
}

The response contains model, answers, and usage, both as MCP structured content and JSON text. Jev may round probabilities to two decimal places, so their sum can differ slightly from 1. The server allows the corresponding rounding margin (up to 0.005 per option) and preserves the returned values without normalization. Choice supports 1–255 named options. Instructions and descriptions may be strings, JSON objects, or arrays; choice descriptions may also be null. Noul accepts optional criteria.true and criteria.false descriptions.

Supply relevant facts, source text, and policies explicitly: Jev cannot see the caller's conversation or local files. Write complete judgments in instructions; IDs are only response keys. Include a no-match option when appropriate. Questions in one batch cannot see one another's answers. A noul near 0.5 is uncertainty about yes/no, not medium intensity. Confidence does not authorize actions or guarantee correctness; evaluate thresholds on representative data.

Troubleshooting

If the tool does not appear after an update, restart the server and open a fresh client session. The configured server is named jev; its tool is jev_decide.

Service/configuration failures are MCP tool errors (isError: true), never invented decisions. Codes include MISSING_API_KEY, INVALID_INPUT, INVALID_RESPONSE, API_ERROR, CONNECTION_ERROR, TIMEOUT, and CANCELLED. Invalid arguments may also be rejected directly by the MCP SDK.

References

• TypeSafe HTTP API
• TypeSafe JavaScript SDK
• Decision primitives and question design
• Function-calling cookbook