Mcpkernel

MCPKernel — The Security Kernel for AI Agents

> Open-source MCP/A2A security gateway that stops tool poisoning, data exfiltration, prompt injection, and rug-pull attacks — with policy enforcement, taint tracking, sandboxed execution, deterministic envelopes, skill auditing, and Sigstore audit for every AI agent tool call. Works with Claude Desktop, Cursor, VS Code, Windsurf, OpenClaw, and any MCP client. OWASP ASI 2026 compliant.

[](https://github.com/piyushptiwari1/mcpkernel/actions/workflows/ci.yml) [](https://pypi.org/project/mcpkernel/) [](https://github.com/piyushptiwari1/mcpkernel) [](https://github.com/piyushptiwari1/mcpkernel) [](LICENSE) [](https://python.org) [](https://pypi.org/project/mcpkernel/) [](https://piyushptiwari1.github.io/mcpkernel/)

> Read the full documentation →

---

What's new in v0.3.0

• Post-execution taint scanning — tool results (content +

structuredContent) are scanned for secrets/PII before the agent ever sees them, plus elicitation responses are auto-tainted as USER_INPUT.

• RFC 8707 enforced by default — OAuth2Auth now requires audience

binding (BREAKING; see [CHANGELOG](CHANGELOG.md)).

• Sigstore Bundle v0.3 + DSSE in-toto audit attestations —

mcpkernel.audit.attest_audit_batch rolls audit records into signed SLSA-ready statements.

• mcpkernel policy-lint — static analysis over rule sets

(PL001–PL007: duplicate IDs, unmatchable rules, ReDoS, shadowed denies, missing OWASP maps).

• Production deployment kit — hardened Helm chart

(deploy/helm/mcpkernel/) and importable Grafana dashboard (deploy/grafana/).

• Supply-chain hardening — CycloneDX 1.6 SBOM attached to every

release, committed uv.lock, native CodeQL workflow, Hypothesis fuzz tests for the JSON-RPC parser.

• Threat model + OWASP LLM Top-10 mapping — see

[THREAT_MODEL.md](THREAT_MODEL.md) and [docs/compliance/owasp-llm-top10.md](docs/compliance/owasp-llm-top10.md).

---

Quick Start

Option A: Security Gateway (proxy mode)

pip install "mcpkernel[all]"
mcpkernel init                                # scaffold .env, policies/, agent.yaml
mcpkernel serve --host 127.0.0.1 --port 8000

Point your MCP client to http://localhost:8000/mcp instead of targeting tool servers directly. Every tool call is now policy-checked, taint-scanned, sandboxed, and audit-logged.

> Every setting can be configured via environment variables — see [.env.example](.env.example) for the full inventory, or mcpkernel init to drop a starter .env in your project.

Option B: MCP Server (tool mode — one command)

pip install mcpkernel
mcpkernel install claude    # or: cursor, vscode, windsurf, zed, openclaw, goose

This adds MCPKernel as an MCP server in your IDE. Your agent can now call mcpkernel_scan_tool, mcpkernel_check_taint, mcpkernel_validate_policy, and more — natively.

Option C: Python API

from mcpkernel import MCPKernelProxy

async with MCPKernelProxy(
    upstream=["http://localhost:3000/mcp"],
    policy="strict",
    taint=True,
) as proxy:
    result = await proxy.call_tool("read_file", {"path": "data.csv"})

Or secure any function with one decorator:

from mcpkernel import protect

@protect(policy="strict", taint=True)
async def read_data(path: str) -> str:
    return Path(path).read_text()

---

Why MCPKernel?

AI agents (LangChain, CrewAI, AutoGen, Copilot, OpenClaw) call tools autonomously — reading files, executing code, making HTTP requests. The MCP ecosystem has 344+ reported security advisories in projects like OpenClaw alone, with critical vulnerabilities including tool poisoning attacks, privilege escalation, data exfiltration, and rug-pull exploits.

MCPKernel is the missing chokepoint. It sits between your agent and MCP tool servers, enforcing security policies on every single call:

┌─────────────┐     ┌──────────────────────────┐     ┌─────────────┐
│  AI Agent    │────▶│       MCPKernel           │────▶│  MCP Tool   │
│ (LangChain,  │◀────│  Security Gateway        │◀────│  Server     │
│ CrewAI,      │     └──────────────────────────┘     └─────────────┘
│ OpenClaw,    │      │ Policy │ Taint │ Sandbox │
│ Cursor, etc) │      │  DEE   │ Audit │ eBPF    │
└─────────────┘      │ Skills │ DLP   │ Doctor  │

What happens to every tool call:

| Step | What MCPKernel Does | |------|-------------------| | 1. Policy Check | Evaluates against YAML rules with OWASP ASI 2026 mappings — blocks or allows | | 2. Taint Scan | Detects secrets (AWS keys, JWTs), PII (SSN, credit cards), and user input in arguments | | 3. DLP Guard | Prevents multi-hop data leaks across tool boundaries (PII in → HTTP out = blocked) | | 4. Sandbox Execution | Runs code in Docker, Firecracker, WASM, or Microsandbox — never on bare metal | | 5. Deterministic Envelope | Hashes inputs/outputs, Sigstore-signs the trace — fully replayable | | 6. Audit Log | Writes to tamper-proof append-only log with SIEM export (CEF, JSONL, CSV, SARIF) |

---

---

The MCP Security Problem

The MCP ecosystem is growing fast — but security hasn't kept pace. Here are the real-world threats MCPKernel defends against:

| Threat | How It Works | Real-World Impact | MCPKernel Defense | |--------|-------------|-------------------|-------------------| | Tool Poisoning | Hidden ` instructions in tool descriptions trick agents into reading SSH keys, .env files, credentials | Cursor, Claude Desktop, any MCP client — credentials exfiltrated silently | **Poisoning Scanner** detects hidden instructions, Unicode obfuscation, blocks | | **Tool Shadowing** | Malicious MCP server injects behavior that overrides trusted servers (e.g., redirects all emails to attacker) | Agent sends data to attacker while appearing to use trusted tools | **Cross-server policy isolation** + taint labels block data from flowing to untrusted sinks | | **MCP Rug Pulls** | Server changes tool descriptions after user approves installation | Trusted tool becomes malicious overnight — no detection | **DEE envelope hashing** pins tool descriptions; drift detection catches changes | | **Privilege Escalation** | Auth reconnect self-claims operator.admin; plugins inherit full host trust | 2 critical CVEs in OpenClaw (GHSA-9hjh, GHSA-fqw4) — RCE via scope widening | **Policy engine** enforces least-privilege; no implicit admin escalation | | **Data Exfiltration** | Agent reads secrets then passes them as hidden parameters to outbound tools | PII, API keys, SSH keys leaked via side-channel in tool arguments | **Taint tracking** + **DLP chain detection** blocks tainted data from reaching sinks | | **Skill Supply Chain** | Malicious OpenClaw/ClawHub skills contain curl\|bash, rm -rf, exfiltration endpoints | User installs skill that backdoors their system | **Skill Scanner** audits SKILL.md for 25+ dangerous patterns before installation | | **Sandbox Escape** | Exec runs on host when sandbox is off (OpenClaw default: sandbox.mode=off`) | Agent code runs with full OS privileges | 4 sandbox backends (Docker, Firecracker, WASM, Microsandbox) — sandbox-first by design | | No Audit Trail | No tamper-proof record of what agents did, when, or why | Impossible to investigate incidents or prove compliance | Sigstore-signed append-only logs with SIEM export (CEF, JSONL, CSV, SARIF) |

> OpenClaw has 344+ security advisories including 2 critical RCE vulnerabilities, scope bypass issues, and webhook authentication gaps. MCPKernel is the security layer that platforms like OpenClaw need but don't have built in.

---

Features

Core Security Pipeline

• YAML Policy Engine — define allow/deny/audit/sandbox rules per tool, argument pattern, or taint label
• Taint Tracking — automatic detection of secrets, PII, API keys, JWTs in tool call arguments
• DLP Chain Detection — prevents multi-hop data leaks across tool boundaries (database → HTTP blocked)
• 4 Sandbox Backends — Docker, Firecracker microVMs, WASM, Microsandbox
• Deterministic Execution Envelopes (DEE) — every execution is hashed and Sigstore-signed for replay
• OWASP ASI 2026 Compliance — built-in policy sets mapping to ASI-01 through ASI-08
• Append-Only Audit Logs — SQLite-backed, content-hashed, with CEF/JSONL/CSV/SARIF SIEM export

Threat Detection & Scanning

• Tool Poisoning Scanner — detects hidden instructions, Unicode obfuscation, and prompt injection in MCP tool descriptions
• Skill Scanner — audits OpenClaw/ClawHub SKILL.md files for dangerous shell commands, exfiltration patterns, and hidden instructions
• MCP Config Discovery — auto-discovers MCP configurations across Claude, Cursor, VS Code, Windsurf, Zed, OpenClaw, Goose
• Snyk Agent Scan Bridge — run Snyk's agent-scan CLI and auto-generate policy rules from findings

Multi-Client Integration

• One-Command Install — mcpkernel install claude adds security tools to any supported IDE
• MCPKernel as MCP Server — expose scan, validate, taint-check, and doctor as native agent tools
• 7 Supported Clients — Claude Desktop, Cursor, VS Code, Windsurf, Zed, OpenClaw, Goose
• OpenClaw Security Skill — installable skill package for the OpenClaw/ClawHub ecosystem

Developer Experience

• Python API — MCPKernelProxy class and @protect decorator for programmatic use
• Policy Presets — built-in permissive, standard, and strict presets — zero-config security
• Doctor Diagnostics — mcpkernel doctor checks Python, dependencies, config, exposed secrets, permissions
• VS Code Extension — TreeView for discovered servers, security findings panel, integrated commands

Platform & Observability

• Kong-Style Plugin Pipeline — pre_execution → execution → post_execution → log with priorities
• Rate Limiting — per-identity token bucket with LRU eviction
• Prometheus Metrics + OpenTelemetry — full observability out of the box
• Optional eBPF Probes — kernel-level syscall monitoring at MCP boundaries
• Agent Manifest Integration — load agent.yaml, convert compliance (FINRA/SEC) to policy rules, block undeclared tools
• Langfuse Observability Export — async batched export to Langfuse for LLM-level analytics
• Guardrails AI Validation — enhanced PII, secret, and toxicity detection via Guardrails hub validators
• MCP Server Registry — discover, search, and validate upstream MCP servers from the official registry

Causal Trust Graph (CTG) — Novel Research Contribution

• Adaptive Trust Decay — tool/server trust erodes exponentially: T(t) = T₀ · e^{-λ(t-t₀)} · Π w(vᵢ)
• Retroactive Taint Invalidation — when a source is compromised, all downstream data is retroactively tainted
• Behavioral Fingerprinting — detects anomalous tool-call patterns via graph topology z-scores
• Minimum Privilege Computation — derives provably minimal permissions from observed causal chains
• Causal Chain Analysis — trace any tool output back to its root data sources

Security Protections (MCP Spec 2025-11-25)

• Confused Deputy Defense — prevents cross-server delegation attacks with tool/server allowlists
• Token Passthrough Guard — blocks credential leakage (OpenAI keys, GitHub PATs, AWS keys, JWTs) in args and results
• SSRF Guard — blocks private networks, cloud metadata (169.254.169.254), with domain allowlists
• Session Hijacking Defense — HMAC-bound sessions with client fingerprint verification and expiry
• Memory Poisoning Defense — detects self-reinforcing injection (Zombie Agents) with repetition scoring
• Unified Security Pipeline — run all checks in a single pipeline.check_tool_call() invocation

Compliance Presets

• One-Line Activation — apply_preset("hipaa", settings) configures all security controls
• 5 Built-in Presets — HIPAA, SOC 2, PCI DSS v4.0, GDPR Article 25, FedRAMP High
• YAML Configurable — set compliance.preset: hipaa in your config file

---

Getting Started

# Install with all backends
pip install "mcpkernel[all]"

# Start the security gateway
mcpkernel serve --host 127.0.0.1 --port 8000

Point your MCP client to http://localhost:8000/mcp instead of targeting tool servers directly.

Add MCPKernel as an MCP Server (agent-callable security tools)

# Install into your IDE — one command
mcpkernel install claude    # Claude Desktop
mcpkernel install cursor    # Cursor IDE
mcpkernel install vscode    # VS Code + Copilot
mcpkernel install windsurf  # Windsurf
mcpkernel install zed       # Zed
mcpkernel install openclaw  # OpenClaw
mcpkernel install goose     # Goose

Once installed, your agent can call these security tools natively:

| MCP Tool | What It Does | |----------|-------------| | mcpkernel_scan_tool | Scan a tool's description for poisoning, shadowing, and prompt injection | | mcpkernel_validate_policy | Validate a YAML policy file for syntax and logic errors | | mcpkernel_discover_configs | Find all MCP configurations on the system | | mcpkernel_check_taint | Check text for leaked secrets, PII, and API keys | | mcpkernel_scan_skill | Audit an OpenClaw/ClawHub SKILL.md for dangerous patterns | | mcpkernel_doctor | Run health diagnostics on the MCPKernel installation |

Run Health Diagnostics

mcpkernel doctor

Checks: Python version, dependencies, config file validity, exposed secrets in environment, tool availability, and file permissions.

Scan Skills Before Installing

# Scan a single skill
mcpkernel scan-skill path/to/SKILL.md

# Scan a directory of skills
mcpkernel scan-skill skills/ --json

Detects: curl|bash pipes, rm -rf, exfiltration endpoints, hardcoded API keys, hidden instructions, undeclared environment variables, and more.

---

Use Cases — Guided Setup

1. Secure AI Coding Assistants (Copilot, Cursor, Windsurf)

Prevent your coding assistant from exfiltrating secrets or overwriting critical files.

pip install "mcpkernel[all]"
mcpkernel init

Add a policy to block sensitive file access:

# .mcpkernel/policies/coding_assistant.yaml
rules:
  - id: CA-001
    name: Block secret file reads
    action: deny
    tool_patterns: ["read_file", "file_read"]
    arg_patterns:
      path: ".*\\.(env|pem|key|credentials)$"

  - id: CA-002
    name: Block outbound HTTP with tainted data
    action: deny
    tool_patterns: ["http_post", "http_request", "fetch"]
    taint_labels: [secret, pii]

Start the gateway and point your MCP client to it:

mcpkernel serve --port 8000
# In your editor's MCP config: http://localhost:8000/mcp

---

2. Autonomous Agent Frameworks (LangChain, CrewAI, AutoGen)

Sandbox every tool call your agents make — no code runs on bare metal.

pip install "mcpkernel[docker]"
mcpkernel init

Configure Docker sandboxing:

# .mcpkernel/config.yaml
sandbox:
  backend: docker
  timeout_seconds: 30

policy:
  default_action: audit   # log everything, deny dangerous calls

Route your framework through MCPKernel:

import httpx

# Instead of calling tools directly, route through MCPKernel
result = httpx.post("http://localhost:8000/mcp", json={
    "method": "tools/call",
    "params": {"name": "execute_code", "arguments": {"code": "print('hello')"}}
})

See full examples: [LangChain](examples/langchain/), [CrewAI](examples/crewai/), [AutoGen](examples/autogen/)

---

3. Enterprise MCP Deployments (OWASP ASI Compliance)

Deploy MCPKernel as the central chokepoint with strict OWASP ASI 2026 policies.

pip install "mcpkernel[all]"
mcpkernel init

# Apply the strict OWASP policy set
cp policies/owasp_asi_2026_strict.yaml .mcpkernel/policies/

# .mcpkernel/config.yaml
policy:
  default_action: deny   # deny-by-default for pro

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [piyushptiwari1](https://github.com/piyushptiwari1)
- **Source:** [piyushptiwari1/mcpkernel](https://github.com/piyushptiwari1/mcpkernel)
- **License:** Apache-2.0
- **Homepage:** https://pypi.org/project/mcpkernel/

Install and usage instructions live in the source repository linked above.