io.github.lennney/mcp-slim-guard MCP Server

The io.github.lennney/mcp-slim-guard MCP server provides schema compression with 83%+ savings and a security proxy for MCP servers. Its described protections include SSRF, injection handling, and rate limit controls, with the stated goal of improving compactness and security for MCP server interactions.

🛠️ Key Features

Schema compression with 83%+ savings
Security proxy for MCP servers
Mitigations for SSRF
Mitigations for injection
Rate limit controls

🚀 Use Cases

Reduce payload size for MCP server schemas via compression
Add a protective layer around MCP server access
Prevent or limit SSRF-related requests
Reduce risk of injection attempts
Enforce request pacing using rate limiting

⚠️ Limitations

Source data does not specify supported protocols, deployment model, or configuration details.

type: Readme title: mcp-slim-guard timestamp: "2026-07-23T18:00:00+08:00" description: Lightweight MCP security proxy — compression (up to 86%) + SSRF protection + allow/deny + audit + rate limiting + injection detection tags:

mcp-slim-guard
readme
mcp
security
compression

中文文档 · English

🛡️ mcp-slim-guard

One proxy. Two superpowers: compression + security.

Node >=18 402 tests 86% compression 5 deps MIT

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?

Problem	Impact	How mcp-slim-guard solves it
Context wasted	Tool schemas eat 60-86% of your context window	5 compression levels, lazy loading, request cache
No access control	Any agent calls any tool with any args	Glob-based allow/deny, fail-closed by default
SSRF	Tool params inject internal network requests	IP blacklist + domain whitelist
Prompt injection	Malicious params execute shell/SQL	17 heuristic patterns, 3 sensitivity levels
Abuse	Unthrottled tool calls flood upstream	Token bucket rate limiter (per-tool configurable)
No audit trail	No record of who called what	Structured JSON audit log with rotation + gzip

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

bash

# 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`

yaml

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

Level	Strategy	Tokens (14 tools)	Savings	When to use
`off`	Passthrough	1,736	—	< 5 tools, or testing
`light`	3 wrapper tools (on-demand schema)	300	-83%	⭐ Default. Best balance for most users
`normal`	2 wrapper tools (no list_tools)	245	-86%	30+ tools, strong LLMs
`extreme`	In-place: strip property descriptions	1,361	-22%	Few tools with complex schemas (10+ params)
`maximum`	In-place: signature only, empty properties	1,294	-25%	Very large individual schemas
`lazy`	Budget preload + on-demand schema	1,644	-5%	30+ tools, most used only occasionally

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

Setup	Tokens/call	Monthly cost (DeepSeek V4)
Without compression	1,736	~$52 (10K calls)
With `light`	300	~$9 (-83%)

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:

code

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

Feature	Description
Multi-server routing	One proxy, multiple upstream MCP servers. Tool names are prefixed (`{server}_{tool}`) for automatic routing.
Hot reload	`kill -HUP <pid>` — zero-downtime config reload. All fields hot-swappable.
Request cache	TTL+LRU in-memory cache for read-only tool results. Per-tool stats.
Streamable HTTP	`mcp-slim-guard start --http --port 3000` — works as a remote MCP endpoint.
STDIO mode	Default. Transparent drop-in for local agents.

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

Command	Description
`mcp-slim-guard init`	Auto-discover `.mcp.json`, generate `mcp-slim-guard.yml`
`mcp-slim-guard validate`	Dry-run policies, show allow/deny for each tool
`mcp-slim-guard start`	Start proxy (STDIO mode)
`mcp-slim-guard start --http --port 3000`	Start proxy (HTTP mode)
`mcp-slim-guard status`	Show config summary + policy overview
`mcp-slim-guard doctor`	Diagnose upstream server connectivity
`mcp-slim-guard audit`	View audit log
`mcp-slim-guard uninit`	Remove mcp-slim-guard.yml and roll back

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

Level	Tokens	Reduction
off	1,736	baseline
light	300	-83%
normal	245	-86%
extreme	1,361	-22%
maximum	1,294	-25%
lazy	1,644	-5%

Latency Overhead