TypeSafe MCP adapts the TypeSafe AI Jev System One API to standard MCP STDIO. It keeps credentials in the process environment, validates requests and responses, retries temporary provider failures safely, and returns typed results to MCP-capable hosts.

At a glance

How it fits

flowchart LR
    host["MCP host<br/>Codex · Claude · Cursor · VS Code"]
    bridge["TypeSafe MCP<br/>typed tools + validation"]
    api["TypeSafe AI API<br/>Jev System One"]
    env["TYPESAFE_API_KEY<br/>process environment"]

    host -->|MCP STDIO| bridge
    bridge -->|validated HTTPS| api
    api -->|typed judgment| bridge
    bridge -->|structured result| host
    env -. never in arguments/output .-> bridge

What you get

Probabilities and confidence are model signals, not proof. verify and gate are deliberately not security boundaries or authorization systems.

Quick start

Run from a checkout

git clone https://github.com/Renwang-Huang/typesafe-mcp.git
cd typesafe-mcp
export TYPESAFE_API_KEY="your-key"
python3 server.py

Install as a command

python3 -m pip install .
typesafe-mcp --version
typesafe-mcp doctor --json

The package has no runtime dependencies. Once uv is installed, run the published PyPI package directly:

uvx typesafe-mcp

To pin the published version:

uvx --from 'typesafe-mcp==0.5.2' typesafe-mcp

For an unreleased source checkout, uvx can also run a pinned Git tag:

uvx --from 'git+https://github.com/Renwang-Huang/typesafe-mcp@v0.5.2' \
  typesafe-mcp

Package layout and compatibility

The legacy package and aliases contain no independent business logic and must not receive new implementation code.

Host setup

The service uses the standard MCP STDIO transport. Every host has its own configuration syntax, but the process and environment contract are the same. For example, a checkout can be registered in a Codex config.toml like this:

[mcp_servers.typesafe]
command = "python3"
args = ["/absolute/path/to/typesafe-mcp/server.py"]
env_vars = ["TYPESAFE_API_KEY"]
startup_timeout_sec = 10
tool_timeout_sec = 60
default_tools_approval_mode = "prompt"
enabled_tools = [
  "route", "review", "classify", "score", "check", "verify", "gate",
  "evaluate", "health"
]

For an installed command:

[mcp_servers.typesafe]
command = "typesafe-mcp"
env_vars = ["TYPESAFE_API_KEY"]
startup_timeout_sec = 10
tool_timeout_sec = 60
default_tools_approval_mode = "prompt"

Keep the key out of host configuration files; env_vars asks the host to forward the environment variable without putting its value in the command line. The same STDIO process can be registered by Claude, Cursor, VS Code, or another MCP host using that host's native configuration format.

The old typesafe-codex-mcp command and typesafe_codex_mcp Python import are kept as migration aliases. Calls to codex_route and codex_review are also accepted, but new configurations should use route and review.

Tools

Example classify call:

{
  "state": "The payment was charged twice.",
  "instructions": "Which team should own this ticket?",
  "labels": {
    "billing": "Payments, invoices, refunds, or duplicate charges",
    "technical": "Bugs, outages, or integration failures",
    "other": "Anything that does not fit the first two labels"
  }
}

CLI and library mode

The MCP process is the default command. The same package can be used in CI:

typesafe-mcp doctor --json
cat request.json | typesafe-mcp evaluate
typesafe-mcp evaluate --input request.json

The Python library is intentionally small:

from typesafe_mcp import TypeSafeClient

client = TypeSafeClient()
result = client.evaluate({
    "state": "A payment failed twice.",
    "questions": {
        "urgent": {
            "type": "noul",
            "instructions": "Does this require urgent handling?",
        }
    },
})

Configuration

Development

python3 -m unittest discover -s tests -v
python3 -m compileall -q .
python3 -m pip wheel --no-deps . --wheel-dir /tmp/typesafe-mcp-dist

The test suite uses local fakes only; it never needs an API key. A live check is opt-in and makes one paid request:

TYPESAFE_API_KEY="your-key" typesafe-mcp doctor --live

See SECURITY.md before using live credentials and BENCHMARK.md for the comparison against the community implementations reviewed during development.

Boundaries

Jev is designed for bounded judgments. Use ordinary code for exact math, date arithmetic, and authorization; use a generative model for prose or code generation. The bridge sends state to TypeSafe, so do not pass secrets or personal data without checking your data-handling requirements.