mcp-slim-proxy

An MCP stdio server that sits between your MCP host (Claude Code, OpenClaw, Cursor — anything MCP-compatible) and your real MCP servers, re-advertising their tools with minified schemas to cut the context tokens spent on tool metadata every single request.

host (Claude Code / OpenClaw)
   │  sees slim schemas
   ▼
mcp-slim-proxy (stdio)
   │  forwards calls unchanged
   ▼
upstream MCP servers (stdio / SSE / streamable-http)

What gets slimmed

Preserved exactly (everything needed to call the tool correctly):

• type structure, required, enum, default, property names

Reduced:

• tool descriptions → first sentence(s) within a budget (default 160 chars)
• parameter descriptions → trimmed to 80 chars (or dropped entirely)
• examples, title, $comment, outputSchema, annotations → removed
• markdown decoration stripped, whitespace collapsed

Typical reduction: 60–85% of tool-schema bytes for verbose real-world servers.

Modes

minify (default) — every upstream tool is advertised with a slim schema. Zero behavior change for the model beyond shorter descriptions.

defer — only two meta-tools are advertised: find_tools (keyword search over the catalog, returns matching slim schemas) and use_tool (invoke by name). Near-zero fixed context cost regardless of how many upstream tools exist; the model pays for schemas only when it needs them. Pin always-available tools via defer.pinned.

OpenClaw note: OpenClaw ≥2026.6 ships this pattern natively as tools.toolSearch — prefer that for OpenClaw gateways. This proxy is for hosts without an equivalent (Claude Code, Cursor) or when you want minify mode's always-visible slim schemas.

Setup

Requires Python ≥3.10.

python3 -m venv .venv
.venv/bin/pip install mcp
cp config.example.json config.json   # edit upstreams

Config:

{
  "mode": "minify",
  "prefixTools": "auto",
  "minify": {
    "toolDescriptionMaxChars": 160,
    "paramDescriptionMaxChars": 80,
    "dropParamDescriptions": false
  },
  "tools": { "deny": [], "allow": [] },
  "defer": { "pinned": [] },
  "upstreams": [
    { "name": "archy", "transport": "sse", "url": "http://host:30765/sse" },
    { "name": "foreman", "transport": "streamable-http", "url": "http://host:30766/mcp" },
    { "name": "vault", "transport": "stdio", "command": "bash", "args": ["/path/start.sh"] }
  ]
}

With multiple upstreams, tools are prefixed <upstream>__<tool> to avoid collisions (prefixTools: "auto"; set true/false to force).

Claude Code

claude mcp add slim -- /path/to/mcp-slim-proxy/.venv/bin/python -m mcp_slim_proxy --config /path/to/config.json

Then remove the wrapped servers from your direct MCP config so the host only sees the proxy.

OpenClaw

"mcp": {
  "servers": {
    "slim": {
      "command": "/path/to/mcp-slim-proxy/.venv/bin/python",
      "args": ["-m", "mcp_slim_proxy", "--config", "/path/to/config.json"]
    }
  }
}

Test

.venv/bin/python tests/run_test.py

Spins up a deliberately verbose upstream, connects through the proxy, and verifies size reduction, schema-structure preservation, call routing, and defer-mode meta-tools.

Limitations

• Upstream tools/list_changed notifications are not yet propagated; the registry is built once at startup. Restart the proxy after changing an upstream's tool set.