jev-shield

September 17, 2026 · View on GitHub

Semantic MCP firewall powered by Jev — a System One verification model. Sits between any MCP client and any MCP server (stdio) and screens, with calibrated probabilities, every tool call, every tool result, and every tool description.

Why another MCP firewall?

Existing MCP security proxies (pipelock, mcpwall, mcp-firewall, Lakera, NeMo Guardrails) are deterministic or pattern-based: they catch payloads that look like known attacks. Attackers paraphrase. Jev catches the meaning of a payload — including phrasings never seen before — and returns a probability, not a boolean, so your policy (not the vendor's) decides what happens.

jev-shield layers three kinds of control:

Layer	What it does	Cost
Structural (deterministic)	Recipient allowlists, required flags, config-owned rules	free
Semantic (Jev, one call per event)	Exfiltration, destructive actions, injection-in-args, credential/payload sensitivity, tool-result injection, secrets in results, tool-description poisoning	~$0.00003/event, ~500ms
Session (taint tracking)	After a result is flagged, subsequent calls are verified under an escalated policy	free

Measured in the bundled demo: 10 verifications, $0.0003 total, median latency 558ms.

What it catches (demo included)

npm install
AI_GATEWAY_API_KEY=... npm run demo

The demo runs a vulnerable MCP server (poisoned tool description, injection in search results, .env leak) behind the firewall and simulates an agent that gets tricked:

tools/list → poisoned tool flagged (tool_poisoning=0.9x)
benign call → passes clean
poisoned search result → REDACTED before the agent ever reads it (contains_injection=0.98)
agent tries exfil → BLOCKED (allowlist + semantics)
legitimate email to ops → passes (semantic discrimination, not keyword)
novel-phrasing exfil inside the allowlist → BLOCKED (payload_sensitivity=0.98)
destructive call → BLOCKED (severity escalation: 2.11 ≥ 2.0)
secret-leaking result → REDACTED (contains_secrets=0.97)

Architecture

MCP client (Claude Code, Cursor, any agent)
        │ stdio
        ▼
┌─ jev-shield ──────────────────────────────────────────┐
│  tools/list → Jev poisoning scan → annotate/hide      │
│  tools/call → structural rules → Jev call battery     │
│               (exfil, destructive, injection, creds)  │
│  result     → Jev result battery → annotate or redact │
│  session    → taint tracking escalates policy         │
│  audit      → JSONL trail: hazards, severity, ms, $   │
└────────────────────┬──────────────────────────────────┘
                     │ stdio
                     ▼
             your real MCP server

Usage

# wrap any stdio MCP server
AI_GATEWAY_API_KEY=<your-key> npx jev-shield -- node path/to/server.js
# custom policy
JEV_SHIELD_CONFIG=./config/policies.json npx jev-shield -- python -m my_server

Point your MCP client's command at jev-shield instead of the server. Everything else is transparent.

Agent skill (Claude Code / opencode / compatible agents)

Give any agent semantic verification of its own risky actions — destructive commands, external sends, secrets/PII, untrusted content:

# zero-install: agents call it directly
echo '{"kind":"call","tool":{"name":"shell_exec","description":"Execute a shell command"},"args":{"command":"rm -rf /var/data"}}' \
  | npx -y github:caiovicentino/jev-shield verify

# or install the skill so agents pick it up automatically
npx -y github:caiovicentino/jev-shield install-skill   # ~/.claude/skills + ~/.config/opencode/skills + /verify command
npx -y skills add caiovicentino/jev-shield -g          # multi-agent: Claude Code, Codex, Cursor, opencode, +70 more

In opencode, /verify <command or text> screens anything on demand. The skill requires AI_GATEWAY_API_KEY in the environment (see .env.example).

Enforcement (hooks & plugins) — opt-in

The skill is cooperative. If you want tool-by-tool enforcement, the hook/plugin layer is opt-in:

Agent	Mechanism	Covers
Claude Code	`PreToolUse` hook → `deny`/`ask` before Bash/Write/Edit/WebFetch/MCP tools; `PostToolUse` hook → flags poisoned tool results to the model	every tool call, incl. MCP
opencode	plugin `tool.execute.before` (throws = block) and `tool.execute.after` (withholds injected results)	every tool call, incl. MCP
Codex	no hook API — enforcement via the MCP firewall: `jev-shield wrap -- <upstream-cmd>` as the MCP server command	every MCP tool call

npx -y github:caiovicentino/jev-shield install-hooks     # opt in: hook + plugin (merges, never clobbers)
npx -y github:caiovicentino/jev-shield uninstall-hooks   # opt out: removes hook + plugin, keeps the skill
JEV_HOOK_OFF=1                                           # kill switch (env), JEV_FAIL_MODE=closed to fail closed

Every check costs ~$0.00003 and adds ~0.5–1.3s to a tool call. Local file reads (Read/Grep/Glob) are exempt by default.

Policy is code, not a prompt

config/policies.json:

{
  "policy": { "review": 0.35, "action": 0.7, "severity_block": 2.0 },
  "hazard_actions": { "data_exfiltration": "block", "destructive_action": "block" },
  "fail_mode": "open",                 // or "closed" if Jev is unreachable
  "tools": {
    "send_email": { "recipient_allowlist": ["@empresa.com"] },
    "delete_records": { "require_flag": { "confirm": true } }
  }
}

Probabilities are the same for every policy; thresholds decide actions. Change policy in code review, not in a prompt.

Honest limits

This is not a security boundary. It is a probabilistic signal layer. Keep sandboxing, least privilege, and human approval for high-stakes actions. (See S. Willison, The lethal trifecta, 2025.)
Determined attackers can try to evade the semantic layer; mitigation is depth: multi-question batteries, severity gating, taint tracking, structural allowlists, and review of the audit trail.
Adds ~500ms per tool call/result (parallel questions, single call). Async/streaming modes are on the roadmap.
State budget per request ≈ 32k tokens; huge tool outputs are truncated for screening.
Depends on TypeSafe early access pricing via AI Gateway; the model layer is abstracted so providers can be swapped.

Roadmap

HTTP/SSE transport support (remote MCP)
Policy packs per industry (healthcare, finance, e-commerce) — community-driven
Streaming-friendly async screening (annotate post-hoc instead of blocking)
Dashboard for the audit trail; export to SIEM
Eval harness: curated adversarial suite (PT-BR + EN) in CI

MIT