CLI Events & Shim

How It Works

The CLI shim acts as a transparent proxy between an MCP client and a real MCP server. The client spawns navil shim instead of the real server binary. Navil spawns the real server as a child process and intercepts every message:

MCP Client (stdin) → [Navil Shim] → Real MCP Server (stdin)
MCP Client (stdout) ← [Navil Shim] ← Real MCP Server (stdout)
                            │
                      Policy check
                      Rate limiting
                      Anomaly detection
                      Telemetry → Redis queue

Usage

Wrap a single MCP server binary:

# Wrap any stdio MCP server
navil shim --cmd "npx -y @modelcontextprotocol/server-filesystem /tmp"

# With agent identity and policy file
navil shim --cmd "python -m my_mcp_server" \
    --agent my-agent \
    --policy policy.yaml

Or wrap all servers in an MCP configuration file at once:

# Wrap all servers in your config
navil wrap mcp_config.json

# Dry run — see what would change without modifying anything
navil wrap mcp_config.json --dry-run

Message Framing

The shim auto-detects the framing format used by the MCP server and supports both common formats:

• NDJSON — Newline-delimited JSON (one JSON-RPC message per line)
• Content-Length — HTTP-style headers (used by the official TypeScript SDK and others)

Responses are always written with Content-Length framing for maximum compatibility.

Security Checks

Every client → server message passes through the full Navil security stack before being forwarded:

1. Sanitization — Request payloads are sanitized using the same engine as the HTTP proxy.
2. JSON-RPC validation — Messages are parsed and validated as proper JSON-RPC 2.0.
3. Policy enforcement — For tools/call requests, the policy engine checks agent permissions against the tool being called.
4. Anomaly gate — If the agent has recent CRITICAL alerts, all calls are blocked until the anomaly is resolved.

Blocked requests return a JSON-RPC error to the client and are never forwarded to the server. Non-tool methods (initialize, tools/list, notifications/*) pass through without policy checks.

Telemetry & Anomaly Detection

After each request/response pair, the shim records telemetry in the background (non-blocking). If Redis is available, events are pushed to the telemetry queue for the cloud worker. Otherwise, anomaly detection runs in-process.

The shim also tracks tools/list responses to register the server's tool inventory for supply chain detection — alerting you if the set of available tools changes unexpectedly.

Runtime Stats

The shim tracks runtime statistics:

Environment Variables

The shim respects the following environment variables: