io.github.gautamvarmadatla/mcpsafetywarden

MCP safety warden is a proxy server that wraps any MCP server and adds behavioral profiling, security scanning, risk gating, and safe execution to its tools.

Contents

• Overview
• Prerequisites
• Installation
• Configuration
• MCP Integration
• CLI Reference
• Auxiliary Integrations
• Development
• Testing
• Further reading

Overview

Use as a proxy to add safety gating to any MCP server, or point it at a server you don't own and run a full security audit without making a single tool call.

Behavioral profiling: Effect class, retry safety, destructiveness. LLM-assisted (Anthropic, OpenAI, Gemini, Ollama) with rule-based fallback. Observed stats (latency p50/p95, failure rate, output size) updated after every proxied call.

Security scanning: mcpsafety+ five-stage pipeline (Recon, Planner, Hacker, Auditor, Supervisor). Cisco AI Defense (AST/YARA). Snyk (metadata analysis). Kali and Burp Suite integrations enrich the pipeline with real network data and HTTP-layer probes. Source code scanning from GitHub with entropy, AST, taint flow, and rug-pull detection.

Safe execution: Argument scanning (20+ attack categories, LLM second-pass). Two-layer output injection scanning. Risk gating with alternatives and per-tool policies. Drift detection on every call and standalone check.

CLI: 24 subcommands, interactive risk menu, --json flag on every command, --yes for CI.

What it detects

• Prompt injection: tool outputs trying to hijack the agent: role hijacking, jailbreaks, fake system prompts, instruction overrides. Detects 11 obfuscation techniques including Unicode lookalikes, zero-width characters, and base64-encoded payloads.
• Malicious tool metadata: descriptions containing injection strings, hardcoded secrets, suspicious download URLs, tool impersonation (shadowing), direct financial execution, system service modification, and untrusted external dependencies. Backed by 19 Snyk checks.
• Argument injection: 20+ attack categories checked on every tool call before the call is forwarded: SSRF to cloud metadata endpoints (AWS, GCP, Azure, Alibaba), path traversal, credential file access (.aws, .ssh, .kube, .env), command injection, SQL/NoSQL/LDAP/XPath injection, XXE, template injection (SSTI), CRLF, null byte, deserialization payloads (Java, Python pickle, PHP, .NET), Windows UNC/ADS attacks, and base64-obfuscated variants of all of the above.
• Source code risks: fetches the server's GitHub source and runs 6 analysis layers: entropy scanning for hardcoded secrets, AST taint flow tracking (parameter to dangerous sink), description-vs-implementation mismatch, Bandit and Semgrep SAST, and LLM cross-function reasoning. Supports Python and TypeScript/JavaScript.
• Rug-pull and drift: stores a SHA-256 hash of the server's source on first scan and alerts if it changes. Catches description swaps, schema changes, and tool removal live on every call via a per-call drift guard.
• Behavior anomalies: classifies every tool by effect class, destructiveness, and 7 risk tags: credential exposure, arbitrary execution, data exfiltration, filesystem access, lateral movement, privilege escalation, and prompt injection surface.
• Composition attacks: analyzes tool sets for chaining risks: IDOR chains, read-write pairs, auth flow exploitation, write-then-execute sequences, and data accumulation + exfiltration paths across multiple tools.
• Network and host risks: when Kali Linux MCP is registered: open ports, running services, OS fingerprint via nmap. When Burp Suite MCP is registered: HTTP-layer active probing and blind SSRF via out-of-band callbacks.
• Credential exposure in outputs: redacts secrets from tool responses before storage. Injection-flagged responses are quarantined and never returned to the calling agent - stored under a run ID for forensic review.
• CVE research and Arxiv findings: the mcpsafety+ Auditor stage cross-references discovered capabilities against known vulnerabilities and recent security research.

Prerequisites

• Python 3.10 or later
• At least one wrapped MCP server to proxy (stdio, SSE, or streamable_http)
• Recommended: an LLM API key (Anthropic, OpenAI, or Gemini)

Without a key the wrapper operates in rule-based-only mode: lower confidence tool classification, regex-only injection scanning, no alternatives in the risk gate, no mcpsafety+ pipeline. For a fully local setup, run Ollama, set OLLAMA_MODEL, and pass --provider ollama explicitly (Ollama is not auto-detected).

Installation

pip install mcpsafetywarden

With all optional extras:

pip install "mcpsafetywarden[all]"

Or specific extras:

pip install "mcpsafetywarden[anthropic,snyk]"

From source:

git clone https://github.com/gautamvarmadatla/mcpsafetywarden
cd mcpsafetywarden
pip install .

The SQLite database is created automatically on first run in the platform user data directory (~/.local/share/mcpsafetywarden/ on Linux, ~/Library/Application Support/mcpsafetywarden/ on macOS, %APPDATA%\mcpsafetywarden\ on Windows). Override with MCP_DB_PATH.

Credential protection (automatic, no action required)

Secret values passed to register_server or onboard_server (Bearer tokens, API keys in headers or env) are automatically detected and replaced with opaque cref_ identifiers before anything touches the model context. The real credential is stored encrypted in the database and resolved silently at connection time. The model, conversation history, and logs only ever see cref_<id>.

Optional: at-rest encryption for stored credentials

pip install cryptography
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Set the printed key as MCP_DB_ENCRYPTION_KEY before starting the server. This encrypts both server credentials and cref_ values at rest.

Configuration

All configuration is via environment variables.

Security note: Never commit API keys or the encryption key. The wrapper strips its own secrets from child process environments before spawning stdio servers.

MCP Integration

Connecting with Claude Desktop

Add the wrapper to claude_desktop_config.json:

{
  "mcpServers": {
    "mcpsafetywarden": {
      "command": "mcpsafetywarden-server",
      "args": [],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "MCP_DB_ENCRYPTION_KEY": "<generated_fernet_key>"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
    }
  }
}

Register each server with the wrapper before use:

mcpsafetywarden register filesystem --transport stdio \
  --command npx \
  --args '["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]'

For a mandatory gateway setup where all tool calls must go through the wrapper, see docs/DEPLOYMENT.md.

Available MCP tools

See docs/TOOLS.md for the full tool reference.

CLI Reference

24 subcommands covering all 25 MCP tools. Every command supports --json for machine-readable output and --yes / -y to skip confirmation prompts.

See docs/CLI.md for the full reference with flags and examples.

Auxiliary Security Tool Integrations

Kali Linux MCP, Burp Suite MCP, and Snyk each integrate automatically once registered. Kali enriches the Recon stage and ping_server with real nmap/traceroute data. Burp adds raw HTTP probing, out-of-band callbacks, and proxy evidence. Snyk analyses tool metadata for injection strings, tool shadowing, hardcoded secrets, and 16 other checks.

See docs/INTEGRATIONS.md for setup instructions.

Development

Install in editable mode:

pip install -e ".[all]"

Run the server and observe logs:

mcpsafetywarden-server 2>server.log

Every module uses logging.getLogger(__name__). The server does not call logging.basicConfig itself - configure logging in your entry point before importing.

Testing

pytest tests/ -v

Set an LLM API key to include LLM-assisted tests; without one they are skipped automatically. See docs/TESTING.md for step-by-step verification of classification, injection scanning, risk gating, and policy enforcement.

Further reading

Contributing

See CONTRIBUTING.md for code standards and pull request guidelines.

License

Apache License 2.0. See LICENSE for details.