SchemaSlim

Local virtualizing reverse-proxy for the Model Context Protocol (MCP). Eliminates Tool Explosion and context window exhaustion by replacing static multi-server tool schemas with on-demand semantic retrieval (schemaslim_search) and lazy proxy dispatch (schemaslim_call).

Architecture

┌─────────────────────────┐
│       LLM Client        │  (Claude Desktop, Antigravity, Cursor)
└────────────┬────────────┘
             │ Exposes exactly 2 Meta-Tools:
             │  • schemaslim_search(query, limit)
             │  • schemaslim_call(namespaced_name, arguments)
┌────────────▼────────────┐
│       SchemaSlim        │  ◄── FastEmbed + sqlite-vec (Dense + FTS5 BM25)
└────────────┬────────────┘
             │ Lazy Persistent Sessions (MCPSessionPool)
    ┌────────┴───────────────────────────┐
    │                                    │
┌───▼──────────────────┐        ┌────────▼─────────────┐
│ Stdio MCP Subprocess │        │    SSE MCP Server    │
│  (GitHub, Git, ...)  │        │   (Postgres, APIs)   │
└──────────────────────┘        └──────────────────────┘

Benchmark & Token Economy

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

Quickstart

1. Installation

Install via uv (recommended) or pip:

# Global tool via uv
uv tool install schemaslim

# Or inside a project virtualenv
pip install schemaslim

2. Configuration

Generate a configuration file:

schemaslim config init

Configure child servers in schemaslim.json (or ~/.schemaslim/config.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./workspace"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
    }
  },
  "settings": {
    "db_path": "~/.schemaslim/index.db",
    "top_k": 3
  }
}

Harvest and index tool schemas into the local vector database:

schemaslim index

3. Client Integration

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "schemaslim": {
      "command": "schemaslim",
      "args": ["serve"]
    }
  }
}

Google Antigravity IDE (antigravity.json)

{
  "mcpServers": {
    "schemaslim": {
      "command": "schemaslim",
      "args": ["serve"]
    }
  }
}

CLI Reference

Security Architecture

SchemaSlim is hardened against common proxy and supply-chain vulnerabilities:

• Host Secret Isolation: Child subprocesses do not inherit os.environ. Only explicitly configured environment variables (config.env) are passed; otherwise, the MCP SDK default environment filter applies.
• Untrusted CWD Protection: Loading configurations from the current working directory (./schemaslim.json) is blocked by default. Requires --allow-cwd or SCHEMASLIM_ALLOW_CWD=1. Trusted global paths (~/.schemaslim/config.json) are prioritized.
• Confused Deputy Prevention: Server identifiers are restricted to ^[a-zA-Z0-9_-]+$ without __. Tool overwrites across server boundaries are strictly rejected by the storage layer.
• DoS & Recursion Guards: The token estimator safely handles deeply nested payloads and circular references without uncaught RecursionError.
• SQLite Variable Safety: Search limit is capped at 20, and all batch queries (WHERE IN) are chunked in batches of 500 parameters.
• Process Timeouts: Child server connections (15.0s) and tool invocations (60.0s) are bounded by timeouts, converting child hangs into structured is_error=True responses.

Configuration Presets

Pre-configured production templates are available in examples/:

• examples/full-stack-dev.json: GitHub, Filesystem, PostgreSQL, and Memory servers.
• examples/minimal.json: Minimal Filesystem and Fetch setup.

Testing

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

uv run pytest -v

License

MIT License © 2026 SchemaSlim Team.