lazy-mcp-router

Safety-first prototype for a local Codex MCP tool gate.

This project does not modify PJ-Monitor and does not modify ~/.codex.

L4 Control Plane Entrypoints

Install from a Git URL:

uv tool install git+https://github.com/<owner>/lazy-mcp-router.git

Product-level commands:

lazy-mcp-router doctor --pretty
lazy-mcp-router doctor --full --pretty
lazy-mcp-router catalog --query git --pretty
lazy-mcp-router onboard --pretty

doctor reports the current L0-L5 level, hard blockers, soft blockers, and next actions. catalog exposes router-visible tools and evidence. onboard previews profile changes by default; onboard --apply is required before any Codex profile config is modified.

Current Loop

search_tools -> describe_tool -> load_server -> call_tool -> audit trace -> status -> cleanup

Safety Contract

Step 2 uses zero-content evidence receipts:

• policy defaults to read-only calls
• missing required env blocks backend startup
• required env is not automatically injected into child processes
• receipts store hashes, policy decisions, latency, state, and redaction evidence
• receipts do not store raw args, raw results, raw stderr, env values, or full schemas
• receipts stay in memory by default; JSONL persistence is opt-in

Safe observability methods:

• healthz()
• status()
• backends()
• tools()
• capabilities()
• receipts_recent()
• receipt(receipt_id)

MCP Control Registry

Step 3 adds a read-only registry layer for local Codex MCP inventory:

• scans ~/.codex/config.toml, ~/.codex/*.config.toml, and ~/.codex/mcp-auto.tsv
• reads only; it does not start servers, inject env values, or modify global config
• builds proof-carrying backend receipts with trust tier and activation level
• uses repo-local router.config.toml or LAZY_MCP_ROUTER_CONFIG for allowlist overlay
• keeps capability output zero-content: no raw args, raw config, env values, or secret tokens

Trust tiers:

• T0_BLOCKED
• T1_OBSERVED
• T2_LOCAL_CANDIDATE
• T3_TRUSTED_REMOTE_CANDIDATE
• T4_CONFIGURED_BACKEND
• T5_RUNTIME_APPROVED

Optional read-only HTTP surface:

• GET /healthz
• GET /status
• GET /backends
• GET /tools
• GET /capabilities
• GET /receipts/recent
• GET /receipts/{id}

The HTTP server binds to 127.0.0.1:7791 by default, supports an optional bearer token, and exposes no write/control routes.

Router Runtime

Step 4 adds the runtime bridge from proof receipts to lazy-startable backends.

Runtime approval is stricter than configuration:

• T4_CONFIGURED_BACKEND means the backend is configured and visible in /capabilities, but it is not startable.
• T5_RUNTIME_APPROVED means the backend passed the runtime gates and is the only tier compiled into LazyMcpRouter.registry.
• runtime_enabled=true is not enough by itself; the configured runtime_fingerprint must match the current canonical runtime contract.
• factory construction, search_tools(), and capabilities() do not spawn backend processes.

Runtime gates:

• remote MCP uses https only, allowlisted hosts, exact allowlisted paths, and rejects userinfo, query strings, and fragments
• direct stdio uses MCP stdio only and requires command/argv allowlisting
• required env is injectable only when the key is both required and env_allowlisted
• env values are resolved only at T5 compile/start boundaries and are never included in receipts, status, capabilities, or HTTP responses
• allowed tools can be declared with tool_risks; undeclared risk remains unknown and is denied unless explicitly allowed

Observability contract:

Endpoint	Scope	Includes	Excludes
GET /capabilities	all T0-T5 inventory	proof, diagnostics, runtime overlay, expected fingerprint hash	raw command, raw URL path/query, env values, allowed tool names
GET /backends	compiled T5 runtime registry only	runtime state, pid, startup latency, call count, missing env keys	T0-T4 candidates
GET /status	aggregate only	capability counts, runtime state counts, audit stats	per-backend detail
GET /tools	declared/loaded tools from compiled T5 backends	tool ids, names, risk, source	raw schemas unless described/loaded

Step 4 keeps HTTP read-only. Control routes such as load_tool and call_tool remain Step 5 work.

Control Plane

Step 5 adds a transport-neutral control core plus HTTP as the first adapter.

Control commands:

• status
• capabilities
• list_backends
• search_tools
• describe_tool
• load_server
• call_tool

All control responses use a safe envelope:

{
  "schema_version": "step5.v1",
  "ok": true,
  "command": "search_tools",
  "result": {},
  "error": null,
  "receipt_id": null,
  "ts": 0.0
}

HTTP control routes:

• POST /control/list_backends
• POST /control/search_tools
• POST /control/describe_tool
• POST /control/load_server
• POST /control/call_tool
• POST /control/status
• POST /control/capabilities

The HTTP adapter reuses the optional bearer token. GET observability routes stay unchanged. Control errors are returned as safe envelopes; raw command args, env values, raw URLs, stderr, and unredacted tool arguments are not returned.

CLI Adapter

Step 5.5 adds a local debug CLI over the same ControlPlane:

lazy-mcp-router status
lazy-mcp-router capabilities
lazy-mcp-router backends
lazy-mcp-router search echo --limit 10
lazy-mcp-router describe '<tool_id>' --no-load
lazy-mcp-router load 'default::server'
lazy-mcp-router call '<tool_id>' --arguments-json '{"message":"hello"}'
lazy-mcp-router call '<tool_id>' --arguments-file args.json
lazy-mcp-router call '<tool_id>' --arguments-stdin

Global flags:

• --codex-dir PATH
• --config PATH
• --pretty
• --no-npx-check
• --env KEY=VALUE

The CLI always prints a step5.v1 JSON envelope. It does not persist daemon state between invocations and does not add policy rules beyond the existing control plane, policy gate, and T5 runtime gates.

MCP Server Adapter

Step 7 adds a stdio MCP server over the same ControlPlane:

lazy-mcp-router-mcp --no-npx-check

It exposes only router meta-tools:

• list_backends
• search_tools
• load_tool
• call_tool

The adapter does not expose backend tools directly, does not mutate router.config.toml, does not inject env values from tool payloads, and does not relax T5 runtime gates. Tool results include the same step5.v1 envelope in MCP structuredContent; content[0].text contains compact JSON for clients that only read text tool output.

For the canonical local runtime, run the MCP adapter as a thin client to the PM2-owned HTTP daemon:

lazy-mcp-router-mcp --proxy-url http://127.0.0.1:7791 --caller codex-mcp

Proxy mode does not construct a direct LazyMcpRouter and does not spawn backend child processes. It forwards the four router meta-tools to POST /control/*, adds safe caller metadata for attribution, and keeps backend runtime state, cooldown, pids, and receipts in the HTTP daemon that PJ-Monitor observes. Direct mode remains available for tests and local development.

Clean-room Codex Smoke

Step 10.10.5 verifies the proxy-mode MCP adapter with an isolated CODEX_HOME instead of codex exec --ignore-user-config. On Codex 0.138.0, the --ignore-user-config path can enumerate the injected MCP server but cancels MCP tool calls during execution. The isolated-home smoke avoids that CLI edge case while still avoiding the user's base ~/.codex/config.toml.

scripts/step10_10_clean_room_smoke

The smoke writes state/step10.10.5-clean-room-smoke.json, isolates config in a temporary Codex home, and uses a temporary auth.json symlink to the existing Codex auth file when available. If that auth file is unavailable, it falls back to codex login --with-api-key from OPENAI_API_KEY. The temporary home is deleted after the run, and token values are never written into the artifact.

Lifecycle Hardening

Step 8 hardens lazy backend runtime behavior:

• state transitions are recorded as receipts
• failed backends enter cooldown before another start attempt
• call timeout clears stale pids and stops router-owned child processes
• backend health probes reconcile dead HOT children during runtime snapshots
• audit receipts are protected by a lock for concurrent control requests
• HTTP control on non-loopback hosts requires a bearer token

Backend runtime rows now include trust tier, activation level, tool count, failure count, cooldown, last transition, and last health probe metadata. They still exclude raw command args, env values, stderr, raw input, and raw output.

PJ-Monitor Observability

Step 9 is consumed by PJ-Monitor through read-only router endpoints:

• /healthz
• /status
• /backends
• /capabilities
• /receipts/recent

The PJ-Monitor MCP Lazy v2 payload can distinguish profile inventory health from router runtime availability. It includes per-endpoint latency/error summaries, read-only path proof, health metadata, backend state/tier/latency/failure rows, and recent receipt summaries. PJ-Monitor does not call router /control/* routes and does not add start/stop buttons for router backends.

Activation Pipeline

Step 10 adds an activation compiler for repo-local rollout checks. It reads router.activation.toml by default. If that file is missing, the compiler returns a safe blocked default instead of touching global Codex config.

Dry-run:

lazy-mcp-router activate --dry-run
lazy-mcp-router activate --dry-run --manifest router.activation.toml --pretty

The dry-run prints a step10.activation.v1 JSON envelope with:

• manifest summary
• router config plan
• shadow profile plan
• capability and T5 readiness
• blocked reasons
• secret redaction proof

Write a repo-local router config plan:

lazy-mcp-router activate --dry-run --write-router-config --config router.config.toml

The generated router.config.toml includes allowlists, runtime fingerprints, env key names, and tool risk metadata. It does not write env values or token values.

Secret values are resolved from the router process environment only. Activation manifests should list env_keys, required_env, and env_allowlist; legacy env = { KEY = "value" } rows are ignored and reported as diagnostics.

Minimal synthetic canary manifest:

[activation]
name = "synthetic-canary"

[[backends]]
profile = "synthetic"
server = "canary"
kind = "synthetic"
command = "/path/to/python"
args = ["tests/fixtures/fake_mcp_server.py", "--scenario", "normal"]
allowed_tools = ["echo"]
tool_risks = { echo = "read" }

Python callers can run the synthetic activation smoke without external GitHub or token dependencies:

from pathlib import Path
from lazy_mcp_router.activation import activation_report

report = activation_report(Path("router.activation.toml"))

The report uses the local fake backend flow search_tools -> load_tool -> call_tool and returns step10.activation_report.v1 JSON-compatible data.

HTTP Daemon

Step 10 also adds a daemon entrypoint over the existing HTTP server:

lazy-mcp-router-http --manifest router.activation.toml --config router.config.toml --host 127.0.0.1 --port 7791 --no-npx-check

Options:

• --manifest PATH
• --config PATH
• --host HOST
• --port PORT
• --token TOKEN
• --no-npx-check

Loopback hosts can run without a token. Non-loopback hosts still require a bearer token through the existing HTTP guardrail.

Real Backend Dual Canary

Step 10.11 adds the first real runtime backend while keeping the synthetic canary as a baseline. The repo-local router.activation.toml now compiles:

• synthetic::canary
• repo-ops::git-mcp

repo-ops::git-mcp is a no-secret remote MCP backend at https://gitmcp.io/docs and is limited to the read-risk fetch_generic_url_content tool. The real canary calls that tool with {"url":"https://gitmcp.io/docs"}.

Local MCP candidates are still discovery-only in Step 10.11. Run:

scripts/step10_11_local_discovery

This writes state/step10.11-local-discovery.json with command names, argument counts, env key names, and recommendations. It does not start or call local MCP servers.

Persistent Shadow Profile Smoke

Step 10.13 turns the persistent lazy-router-shadow profile into a repeatable acceptance check. It reads /home/crazy/.codex/lazy-router-shadow.config.toml, verifies that the profile exposes only lazy-mcp-router, and blocks before running Codex if direct MCP servers such as git-mcp reappear.

scripts/step10_13_shadow_profile_smoke

The smoke runs Codex with the real shadow profile:

codex exec -p lazy-router-shadow -s read-only -C /home/crazy/lazy-mcp-router --skip-git-repo-check

It then exercises the router meta-tool path list_backends -> search_tools -> load_tool -> call_tool against the repo-ops::git-mcp canary and writes state/step10.13-shadow-profile-smoke.json. The artifact records profile server names, router/PJ-Monitor postflight status, backend call evidence, and sanitized Codex command output. It does not set CODEX_HOME, does not modify ~/.codex, and does not store token or env values.

Fake Backend Scenarios

• normal_backend
• slow_start_backend
• crash_on_start_backend
• hang_on_call_backend
• duplicate_tool_backend
• secret_leak_backend

Real Smoke

Phase 3 uses GitMCP through the documented mcp-remote stdio bridge:

npx -y mcp-remote https://gitmcp.io/docs

Run the live smoke test explicitly:

RUN_GIT_MCP_SMOKE=1 uv run pytest -q tests/test_phase3_mcp_stdio.py::test_git_mcp_docs_real_smoke -s

Step 4 factory/runtime tests cover the local T5 bridge. A future live load-only smoke can use the same GitMCP bridge without calling tools.

Verification

uv run pytest -q
uv run ruff check .