# Jev Tool Router

Jev-powered MCP tool routing for Codex.

Unofficial community project. Not affiliated with or endorsed by TypeSafe AI,
Vercel, or OpenAI.

Instead of exposing hundreds of external MCP tool schemas directly to the
agent, Jev Tool Router exposes a small routing surface and resolves external
tool discovery on demand.

The core flow is:

    agent: "I need capability X"
                  |
                  v
        jev_router/find_tool
                  |
                  v
      Jev sees request + tool
        names + descriptions
                  |
          +-------+-------+
          |               |
      >= threshold     < threshold
          |               |
          v               v
    one tool + schema   full tool list
          |
          v
       call tool
          |
    failure or mismatch
          |
          v
      full discovery

Default selection threshold: 0.90.

## Why

Large MCP setups can expose hundreds of tool definitions to an agent even when
only one tool is relevant to the current task. This project moves external MCP
tool discovery behind a small router:

- find_tool
- get_tool_schema
- list_all_tools
- call_readonly_tool
- call_tool
- evaluate_work_with_jev
- router_status

The underlying tool inventory remains available. The router narrows discovery;
it does not permanently remove the fallback path.

## What Jev does

For routing, Jev receives:

- the capability the agent is looking for
- optional task context
- tool names
- tool descriptions

It does not receive every full input schema during routing.

Every routing choice includes none_of_the_above. A tool is selected only when
its probability reaches the configured threshold. Otherwise the router returns
the normal full routed-tool list.

If the inventory is larger than Jev's Choice option limit, the router runs a
conservative tournament. Each group produces a finalist, finalists are compared
again, and final confidence is the minimum confidence along the winning path.

## Requirements

- Node.js 22 or newer
- Codex CLI/Desktop
- Vercel AI Gateway API key in AI_GATEWAY_API_KEY
- Access to typesafe-ai/jev through Vercel AI Gateway

The API key is never written into router.config.json or Codex config.

## Install as a skill

Install directly from GitHub:

    npx skills add jackbarunz/jev-tool-router --global -y

Then ask your coding agent to set up Jev Tool Router, or follow the manual
steps below.

## Manual quick start

Clone and install:

    git clone https://github.com/jackbarunz/jev-tool-router.git
    cd jev-tool-router
    npm install
    npm run check
    npm test

Preview which Codex MCP servers would be moved behind the router:

    npm run setup:codex

Apply the migration:

    npm run setup:codex -- --apply

Keep specific MCP servers direct:

    npm run setup:codex -- --apply --exclude=my_server,another_server

Then restart Codex and check:

    npm run status
    codex mcp list

## What setup changes

The setup script:

1. Reads ~/.codex/config.toml.
2. Leaves native Codex entries such as node_repl, cua_repl, and codex_app
   direct.
3. Converts eligible external MCP entries into
   ~/.codex/jev-tool-router/router.config.json.
4. Skips remote entries with explicit Codex auth semantics or custom
   bearer/header authentication rather than guessing how to proxy them.
5. Skips stdio entries that contain literal env values rather than copying
   possible credentials into router.config.json. env_vars names are supported.
6. Skips stdio args and remote URLs that look like they contain embedded
   credentials.
7. Keeps disabled/required MCPs and servers with custom Codex approval/output
   policy direct instead of weakening their semantics.
8. Preserves eligible per-server tool allow/deny lists and startup/tool
   timeouts inside the router config.
9. Merges newly migrated servers with servers already routed by an earlier run,
   so setup is safe to rerun.
10. Validates any existing jev_router registration points to this installation;
    a stale or unrelated same-name registration makes apply fail before any
    direct MCP is removed.
11. Creates timestamped backups of config.toml, AGENTS.md, and an existing
    router config before mutation.
12. Registers jev_router before removing any migrated direct MCPs.
13. Removes migrated external MCPs through `codex mcp remove`.
14. Appends routing instructions to ~/.codex/AGENTS.md if they are not already
    present.

The generated router config lives under the user's Codex configuration
directory, not inside this repository. A root-level router.config.json is still
gitignored for local/manual overrides. The generated config may contain
machine-specific executable paths and environment-variable names, but the
automatic migration refuses literal env values and credential-like args/URLs.

## Remote MCPs and OAuth

Plain remote URL MCP entries are wrapped with mcp-remote. On first use, an
OAuth-capable server may open its own authorization flow. This is expected.

Remote servers configured with bearer token environment variables or custom
HTTP headers, as well as servers using explicit Codex auth modes such as
`auth = "oauth"` or `auth = "chatgpt"`, are intentionally not
auto-migrated. Keep them direct or provide a safe stdio wrapper whose auth
semantics you control.

The wrapper version used by automatic migration is pinned so a future
mcp-remote release cannot silently change an existing generated command.

## Example

Suppose the routed inventory contains 273 tools.

Request:

    I need to generate a video with one of my connected external tools.

Jev may return:

    mode: selected
    tool: video_generation/generate_video
    confidence: 0.97

For an intentionally vague request:

    I need some external tool, but I do not know which capability.

The winning probability may remain below 0.90, so find_tool returns
fallback_full_list with the complete routed inventory.

## Failure behavior

Technical failure:

    call_tool
      -> fallbackRequired: true
      -> allTools: [...]

Semantic mismatch:

    selected tool technically succeeds
      -> agent sees it was the wrong capability
      -> list_all_tools
      -> choose from full inventory

This makes the optimization reversible on every turn.

If a downstream MCP connection becomes unhealthy, the router evicts that
session and rebuilds discovery through a fresh connection. Tool execution is
not automatically replayed after an uncertain transport failure: replaying a
mutating tool could duplicate a side effect.

## Work evaluation

The router also keeps the separate Jev workflow used to review completed work:

    "Evaluate the work with Jev."

Codex can call evaluate_work_with_jev to score:

- requirement satisfaction probability
- completion probability
- revision probability
- quality on a 0-4 rubric
- primary issue category

## Scope

The automatic setup targets external MCP servers configured under Codex
mcp_servers.

Built-in OpenAI/Codex browser, computer-use, filesystem, and internal runtime
tools remain native.

Plugin-owned tool surfaces can exist outside mcp_servers. If a plugin duplicates
a server that was moved behind the router, disable that plugin separately only
when you actually want to hide its direct tool surface.

## Configuration

See templates/router.config.example.json.

By default the runtime reads:

    ~/.codex/jev-tool-router/router.config.json

Set JEV_ROUTER_CONFIG to use an explicit config path instead.

Main options:

- model: defaults to typesafe-ai/jev
- threshold: defaults to 0.90
- maxJevChoices: defaults to 200; must remain at most 254 because the router
  reserves one Choice option for none_of_the_above
- descriptionMaxChars: tool-description characters passed to Jev
- inventoryTtlMs: cached MCP inventory lifetime
- connectTimeoutMs: default downstream MCP connection timeout
- toolTimeoutMs: default downstream tool-call timeout

Per-server config can also include envVars, connectTimeoutMs, toolTimeoutMs,
enabledTools, and disabledTools. Literal env objects are intentionally rejected;
inherit secrets by environment-variable name instead.

## Related work

fast-jev-compaction by Tamara Tran uses Jev for a complementary problem:
deciding which historical tool calls/results should remain in conversation
context during compaction.

https://github.com/tamaratran/fast-jev-compaction

Jev Tool Router acts earlier in the loop: it reduces the external MCP tool
surface before tool selection.

## License

MIT.