Jev Decision MCP

A local stdio MCP server exposing one tool, jev_decide, for typed decisions through any SDK-compatible decision API endpoint. Point it at an endpoint with BASE_URL and MODEL; there is no provider preset, host allowlist, or model allowlist. Written in TypeScript with the official MCP SDK and the @typesafe-ai/sdk typed-decision SDK.

Independent community project; not affiliated with the SDK vendor. 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 for the decision endpoint you configure (API_KEY). It is required for decision calls only — the tool can be discovered without one.

What "SDK-compatible" means here. Compatibility is the typed-decision contract of the @typesafe-ai/sdk: the endpoint must implement the SystemOne request (POST {BASE_URL}/v1/systemone) that returns typed choice/score/noul answers with probability distributions and usage counts.

Related MCP server: Codex Gemini MCP

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.3.0

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

{
  "mcpServers": {
    "jev": {
      "command": "npx",
      "args": ["-y", "jev-decision-mcp@0.3.0"],
      "env": {
        "API_KEY": "YOUR_API_KEY",
        "BASE_URL": "https://api.example.com/decisions",
        "MODEL": "your-model-name"
      }
    }
  }
}

Alternatively, set API_KEY, BASE_URL, and MODEL in the environment that launches your client and omit env if the client forwards those variables. 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.3.0

Then use "command": "jev-decision-mcp" with no arguments in your MCP client, and supply the same API_KEY, BASE_URL, and MODEL values.

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.

Endpoint configuration

BASE_URL and MODEL are required at startup and are fixed for the life of the process; tool calls can override only the model name. There is no runtime preset selector: the server never switches endpoints or credentials per call, and it applies no host or model allowlist beyond URL validation. BASE_URL is a prefix — the SDK appends /v1/systemone to it — so HTTP(S) URLs with custom path prefixes are supported.

Reference endpoints (examples only; no provider is implied or endorsed). These are known SDK-compatible endpoints you can copy into BASE_URL/MODEL with your own API_KEY:

Two instances to compare endpoints. Configure one instance per endpoint and send the same request to each instance's jev_decide:

{
  "mcpServers": {
    "jev-a": {
      "command": "npx",
      "args": ["-y", "jev-decision-mcp@0.3.0"],
      "env": {
        "API_KEY": "YOUR_FIRST_API_KEY",
        "BASE_URL": "https://api.typesafe.ai",
        "MODEL": "jev-latest"
      }
    },
    "jev-b": {
      "command": "npx",
      "args": ["-y", "jev-decision-mcp@0.3.0"],
      "env": {
        "API_KEY": "YOUR_SECOND_API_KEY",
        "BASE_URL": "https://api.liquid.ai/decisions",
        "MODEL": "d1-ultra"
      }
    }
  }
}

Each instance stays on its own fixed endpoint, so a comparison always shows exactly one endpoint per call.

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.3.0"]
env_vars = ["API_KEY", "BASE_URL", "MODEL"]
tool_timeout_sec = 45

Set API_KEY, BASE_URL, and MODEL in the environment that launches Codex; env_vars forwards their existing values 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 API_KEY, BASE_URL, and MODEL, or supply them 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 configuration through Codex's environment instead of .env.

To verify your build, run npm run check (type checking and tests with mocked API responses; no network 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. Only these four are read:

Required vs optional. BASE_URL and MODEL must be set explicitly at startup; the server exits with a configuration error otherwise and never falls back to SDK or vendor defaults. API_KEY is optional at startup so a client can discover jev_decide without a key; decision calls without it return MISSING_API_KEY. Whitespace-only values count as unset.

Model precedence (highest first): the per-call model argument, then MODEL. A blank or whitespace-only per-call model is rejected with INVALID_INPUT; it can never fall back to a blank or hidden default. A per-call model changes only the model name in the request; the credential and destination stay fixed.

Endpoints are fixed by the operator, not by the tool. The process sends every request to the configured BASE_URL; tool input cannot change the destination, and there is no provider host or model allowlist — BASE_URL accepts any host and any path prefix (including localhost for self-hosting). BASE_URL must be an absolute http:/https: URL without credentials, query, or fragment; values containing ? or # are rejected at startup so no empty query or fragment delimiters can be appended. State and questions are sent to the configured endpoint and may incur API charges. The server does not persist inputs or decisions, and upstream error bodies are not exposed.

Timeout. JEV_TIMEOUT_MS is the total deadline for one decision call, including automatic SDK retries (individual attempts are capped at 10 seconds). Keep your client's tool timeout above JEV_TIMEOUT_MS / 1000 seconds.

Migrating from 0.1.3. Version 0.1.3 read TYPESAFE_API_KEY and TYPESAFE_DEFAULT_MODEL (default jev-latest) and always sent requests to https://api.typesafe.ai. Rename TYPESAFE_API_KEY to API_KEY and TYPESAFE_DEFAULT_MODEL to MODEL; if you relied on the old default model, set MODEL=jev-latest explicitly. Add BASE_URL=https://api.typesafe.ai to keep the endpoint 0.1.3 used. Finally, update your pinned package configuration to jev-decision-mcp@0.3.0 and restart or reload the host so the new process picks up the renamed variables.

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 never repairs returned values: everything is passed through exactly as the API sends it, probabilities are never renormalized, and token counts are never invented. A response with null usage counts is an incompatibility and is rejected as INVALID_RESPONSE rather than reporting fabricated zeros. Choice supports 1–255 named options.

The accepted input shapes are unchanged: instructions and descriptions may be strings, JSON objects, or arrays; choice descriptions may be null; noul accepts optional criteria.true and criteria.false descriptions, which may be null. On the request wire the server makes exactly one normalization: a noul criterion description of null is omitted from the outgoing request, and a criteria object with no remaining description is omitted entirely. This is a provider-agnostic canonical omission of unset optional descriptions — some endpoints reject a sent null noul description with HTTP 422 while reading an omitted description as undescribed (observed on the Liquid reference endpoint; omission resolved it). Everything else travels exactly as supplied: non-null noul descriptions, including structured objects and arrays with nested nulls, and all choice and score values, including null choice 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. With the two-instance comparison setup both servers expose jev_decide; their server names (jev-a, jev-b) tell the instances apart.

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. Startup fails with a configuration error when BASE_URL or MODEL is missing or malformed; the error names the variable but never echoes values.

References

• TypeSafe JavaScript SDK — the @typesafe-ai/sdk used by this server

• TypeSafe HTTP API — the typed-decision (SystemOne) request this server performs

• Decision primitives and question design

• Function-calling cookbook