navil wrap vs navil shim -- What is the Difference and Why It Matters

You've seen both commands in the docs. They look separate. They're actually one pipeline.

The Pipeline

navil wrap is the setup tool. navil shim is the enforcement layer. Understanding the relationship between them saves debugging time and explains why Navil works the way it does.

navil wrap: The Convenience Command

navil wrap reads your MCP config file and rewrites each server entry to use navil shim as the command. That's it. It handles the file editing so you don't have to.

navil wrap config.json

Before:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["server-filesystem"]
    }
  }
}

After:

{
  "mcpServers": {
    "filesystem": {
      "command": "navil",
      "args": ["shim", "--cmd", "npx server-filesystem"]
    }
  }
}

The config now routes through Navil. wrap never runs at runtime -- it's a one-time setup step.

navil shim: The Runtime Binary

navil shim is the actual binary that sits between your MCP client and server. It:

• Intercepts stdio from both directions
• Runs the security pipeline (sanitize -> parse -> policy -> anomaly detection)
• Forwards traffic unchanged if it passes all checks
• Blocks or flags violations

You never call shim directly. wrap sets it up so the MCP client invokes it automatically.

# You run this once:
navil wrap config.json
 
# This runs continuously at runtime (automatically):
navil shim --cmd "npx server-filesystem"

The Flow

User runs:        navil wrap config.json
                  |
wrap rewrites:    Each "command" -> "navil"
                  Each "args" -> ["shim", "--cmd", "original command"]
                  |
At runtime:       MCP client starts navil shim
                  |
shim intercepts:  Sanitize -> Parse -> Policy -> Anomaly
                  |
shim forwards:    Clean traffic to the MCP server

Useful Flags

--dry-run: Preview the changes without writing to disk.

navil wrap config.json --dry-run

--undo: Restore your original config.

navil wrap config.json --undo

--only: Wrap only specific servers.

navil wrap config.json --only filesystem,github

--policy: Attach a policy file during wrap.

navil wrap config.json --policy security-policy.json

Why This Matters for You

Debugging: Logs from the security pipeline come from shim. If you're investigating a policy violation or anomaly, you're reading shim logs.

Custom Setups: Not all MCP configs fit the standard pattern. Understanding that wrap is just a config rewriter means you can manually wrap non-standard setups or integrate Navil into custom tooling.

Performance: When you read benchmarks or tune Navil's latency, you're tuning shim. The overhead is in the runtime binary, not the setup tool.

Integration: If you're building tooling on top of Navil, you probably want to call shim directly with custom flags, not wrap. Now you know why.

One Setup, Continuous Enforcement

The design is clean: wrap is boring and one-time. shim is everywhere and always running. Once you understand the split, the entire system makes sense.

Next steps: Run navil wrap --help to see all available flags, or check the quick start guide for a full walkthrough.