SchemaSlim

Local JIT virtualizing reverse-proxy for Model Context Protocol.

Connecting dozens of MCP servers causes severe Tool Explosion: loading hundreds of static tool schemas consumes 15,000–30,000 prompt tokens before a conversation even begins, inflating LLM costs and degrading reasoning quality. SchemaSlim replaces static tool schemas with exactly 2 dynamic meta-tools (schemaslim_search and schemaslim_call), reducing context overhead by 70–90% through fast local hybrid retrieval (sqlite-vec + FTS5 + FastEmbed) with zero external API calls.

Architecture & Data Flow

┌─────────────────────────────────────────────────────────────┐
│              LLM Client (Claude / Antigravity / Cursor)     │
└──────────────────────────────┬──────────────────────────────┘
                               │ Exposes only 2 Meta-Tools:
                               │  • schemaslim_search(query, limit)
                               │  • schemaslim_call(namespaced_name, arguments)
┌──────────────────────────────▼──────────────────────────────┐
│                  SchemaSlim Virtual Proxy                   │
│                                                             │
│   FastEmbed (BGE-small)  ◄── Hybrid Search ──►  sqlite-vec  │
│   Dense Embeddings 384d                         BM25 FTS5   │
└──────────────────────────────┬──────────────────────────────┘
                               │ Lazy Persistent Sessions (MCPSessionPool)
          ┌────────────────────┴───────────────────┐
          │                                        │
┌─────────▼──────────────┐              ┌──────────▼──────────────┐
│  Stdio Subprocesses    │              │  Remote SSE Endpoints   │
│  (GitHub, FS, Git...)  │              │  (Postgres, Motion, API)│
└────────────────────────┘              └─────────────────────────┘

One-Command Quickstart

1. Install via uv tool

uv tool install schemaslim

(Or install in an active Python virtual environment via pip install schemaslim)

2. Wrap Existing MCP Clients Instantly

Automatically discovers configurations for Claude Desktop, Google Antigravity, Cursor, and VS Code, creates safe .schemaslim.bak backups, migrates server definitions to the global registry, and routes client traffic through SchemaSlim:

schemaslim wrap

To roll back at any time:

schemaslim unwrap

Key Features

• Zero Configuration Overhead: One command (schemaslim wrap) auto-detects client configurations and virtualizes all tools in seconds with interactive confirmation (Space / Enter).
• 100% Local Hybrid Semantic Indexing: Combines vector similarity (sqlite-vec + ONNX FastEmbed BGE-small-en-v1.5) and lexical keyword ranking (SQLite FTS5 BM25). Runs entirely offline with 0 API keys and zero network latency.
• Dual-Mode Operation:
  • Pure stdio RPC transport (clean JSON-RPC channel on stdout).
  • Live TUI telemetry dashboard on stderr (schemaslim serve --tui) showing real-time token savings and tool call latency.
• Resilient & Cross-Platform:
  • Full Windows UTF-8 BOM (utf-8-sig) handling for flawless PowerShell compatibility.
  • Automatic /sse URL normalization and fallback for remote endpoints.
• Hardened Security Perimeter:
  • Untrusted current working directory (CWD) configs blocked by default.
  • Process environment isolation preventing host secrets from leaking to child MCP tools.
  • Strict server namespace boundaries preventing confused deputy attacks.

Token Economy & Benchmark

Measured on 4 realistic MCP servers (git_server, db_server, fs_server, api_server) with 20 tools:

Commands Cheatsheet

Security Architecture

• Host Secret Isolation: Child subprocesses do not inherit os.environ. Only explicitly configured environment variables are forwarded.
• Untrusted CWD Protection: Loading configurations from the current working directory (./schemaslim.json) is blocked by default; requires explicit --allow-cwd or SCHEMASLIM_ALLOW_CWD=1.
• Confused Deputy Prevention: Tool overwrites across server boundaries are strictly blocked; server IDs must match ^[a-zA-Z0-9_-]+$.
• DoS & Recursion Guards: The schema token estimator is bounded against circular structures and deeply nested schemas.
• SQLite Parameter Chunking: Batch queries are split into chunks of 500 parameters to maintain compatibility across all SQLite engine limits.
• Process Timeouts: Subprocess lifecycle and tool invocations are guarded by strict timeouts (15s connect, 60s execution).

Testing & Verification

Run the full automated test suite (104 unit, integration, and security tests):

uv run pytest -v

License

MIT License © 2026 SchemaSlim Team.