🛡️ mcp-slim-guard

type: Readmetitle: mcp-slim-guardtimestamp: "2026-07-23T18:00:00+08:00"description: Lightweight MCP security proxy — compression (up to 86%) + SSRF protection + allow/deny + audit + rate limiting + injection detectiontags:

• mcp-slim-guard
• readme
• mcp
• security
• compression

中文文档 · English

🛡️ mcp-slim-guard

One proxy. Two superpowers: compression + security.

mcp-slim-guard sits between your AI agent and MCP servers, transparently adding schema compression (5 levels, up to 86% token reduction) and security policies (SSRF protection, tool allow/deny, injection detection, rate limiting, audit logging).

graph LR
    A[AI Agent] --> B[mcp-slim-guard]
    B --> C[Compression Pipeline]
    B --> D[Security Pipeline]
    C --> E[MCP Server 1]
    C --> F[MCP Server N]
    D --> E
    D --> F
    style B fill:#4a90d9,color:#fff
    style C fill:#e6f3ff
    style D fill:#ffe6e6

Why mcp-slim-guard?

Only mcp-slim-guard combines compression AND security in a single proxy. Other tools compress schemas but don't protect you. Security proxies don't save you tokens.

Quick Start

# Install
npm install -g mcp-slim-guard

# Auto-discover MCP servers from your .mcp.json
cd your-project/
mcp-slim-guard init

# Dry-run policies to check for false positives
mcp-slim-guard validate

# Start the proxy
mcp-slim-guard start

Your agent now connects to mcp-slim-guard instead of the original servers. That's it.

MCP servers are auto-discovered from .mcp.json, mcp.json, or claude_desktop_config.json.

Generated mcp-slim-guard.yml

tools:
  allow: ["search_*", "read_*"] # only allow search/read tools
  deny: ["*_delete_*", "*_admin_*"] # block dangerous ops
ssrf:
  mode: block
  block_private_ips: true
  allow_domains: ["*.github.com"]
rate_limit:
  default: 60/min # per-tool rate limit
injection_detection:
  enabled: true
  mode: block
  sensitivity: medium
compressor:
  enabled: true
  level: light # 5 levels: off/light/normal/extreme/maximum
cache:
  enabled: false # TTL+LRU read-only response cache
audit:
  output: file # structured JSON audit log
  maxSize: 10MB
  maxFiles: 5

Features

🗜️ Schema Compression — Reclaim Your Context Window

Why the big gap? light/normal replace all tools with 2-3 wrapper tools (mcp__invoke_tool, mcp__get_tool_schema). The LLM fetches schemas on demand. extreme/maximum keep all tools and only compress each schema in place — savings depend on schema complexity.

Real-world cost impact

Accuracy verified

Benchmarked against DeepSeek V4 Flash across 12 scenarios × 5 levels × 3 runs = 180 API calls. Run it yourself →

🛡️ Security Pipeline — Defense in Depth

Every tool call runs through a serial pipeline. First rejection stops execution:

Agent Request
     │
     ▼
┌─────────────────┐
│  1. Allow/Deny  │  ← Glob pattern matching. Fail-closed.
│  (Whitelist)    │
└────────┬────────┘
         ▼
┌─────────────────┐
│  2. SSRF Shield │  ← IP blacklist + domain whitelist.
│                  │     Blocks 10.*, 192.168.*, 169.254.*
└────────┬────────┘
         ▼
┌─────────────────┐
│  3. Injection   │  ← 17 heuristic patterns:
│     Detection   │     Shell/SQL/NoSQL/Prompt injection
└────────┬────────┘
         ▼
┌─────────────────┐
│  4. Rate Limit  │  ← Token bucket. Per-tool or global.
│                  │     Default: 60 req/min/tool
└────────┬────────┘
         ▼
┌─────────────────┐
│  5. Audit Log   │  ← Structured JSON. Rotate + compress.
│                  │     Every decision recorded.
└────────┬────────┘
         ▼
   Upstream MCP Server

🔄 Additional Capabilities

How It Works

sequenceDiagram
    participant LLM as AI Agent
    participant MM as mcp-slim-guard
    participant US as Upstream MCP Server

    LLM->>MM: tools/list
    Note over MM: Compression pipeline<br/>filters + transforms tools
    MM-->>LLM: compressed tool list (light: 3 wrappers)

    LLM->>MM: mcp__get_tool_schema("search")
    MM-->>LLM: full schema for "search"

    LLM->>MM: mcp__invoke_tool("search", {q: "..."})
    Note over MM: Security pipeline<br/>whitelist → ssrf → injection → ratelimit
    MM->>US: forward call
    US-->>MM: result
    Note over MM: Audit log entry
    MM-->>LLM: result

CLI Reference

Benchmarks

All benchmarks use real MCP server tool schemas (filesystem server, 14 tools) with tiktoken (gpt-4o encoding). Run them yourself: npm run bench

Token Savings

Latency Overhead

Policy pipeline:      ~2ms/call  (whitelist → ssrf → injection → ratelimit)
Compression (light):  <0.05ms
Cache hit:            0.01ms

Accuracy (DeepSeek V4 Flash)

12 scenarios × 5 levels × 3 runs = 180 API calls. Scenarios include 4 fuzzy-name tests (read vs search, list vs tree).

Comparison

Requirements

• Node.js >= 18
• Only 5 production dependencies (MCP SDK, commander, js-yaml, micromatch, pino)

Docker

docker build -t mcp-slim-guard .
docker run -i --rm -v $(pwd)/mcp-slim-guard.yml:/app/mcp-slim-guard.yml mcp-slim-guard start

License

MIT