How to Enable MCP Shrink Middleware in Caveman: Complete Setup Guide

Use the --with-mcp-shrink="<upstream cmd>" flag when running the Caveman installer to automatically proxy your MCP server through the shrink middleware, which compresses large text fields like description to reduce token usage without modifying code or URLs.

The Caveman toolkit provides a shrink middleware that proxies Model Context Protocol (MCP) servers to compress verbose textual responses before they reach your AI client. This guide explains how to enable MCP shrink middleware in Caveman using the automated installer or manual configuration, based on the JuliusBrussee/caveman source code.

How the MCP Shrink Middleware Works

The middleware operates as a transparent proxy between your MCP client (Claude Code, Opencode) and the upstream MCP server. It intercepts JSON-RPC messages and compresses specified fields before forwarding them downstream.

Argument Parsing in the Installer

The installer script (bin/install.js) handles the --with-mcp-shrink flag in the argument-parsing section at lines 66-78. When present, the flag value is tokenized into an array and stored in opts.withMcpShrink, representing the upstream command to proxy (e.g., ["npx","@modelcontextprotocol/server-filesystem","/my/repo"]).

Wiring the Proxy via installMcpShrink

After detecting the flag, the installer calls installMcpShrink(ctx) around line 1030 of bin/install.js. This function probes the npm registry for the caveman-shrink package and, upon confirmation, injects a new MCP server entry into your client's configuration file. The generated entry follows this structure:

"caveman-shrink": {
  "type": "local",
  "command": ["npx", "-y", "caveman-shrink", "<upstream tokens …>"],
  "enabled": true
}

Compression Logic in the Proxy Server

The actual transformation occurs in src/mcp-servers/caveman-shrink/index.js. The transformResponse function (lines 73-108) reads JSON-RPC messages line-by-line from the upstream server, compresses fields listed in CAVEMAN_SHRINK_FIELDS (defaulting to description), and streams the modified responses to the client.

Methods to Enable the Middleware

Via the Installer (Recommended)

The simplest method uses the installer flag to automatically configure your client:

caveman --with-mcp-shrink="npx @modelcontextprotocol/server-filesystem /path/to/project"

Replace the command after the flag with any executable that starts an MCP server. The installer performs the following actions:

1. Validates that caveman-shrink is available in the npm registry
2. Adds the caveman-shrink entry to the appropriate client configuration file
3. Enables the proxy immediately for the next client session

Manual Configuration

For advanced use cases, manually edit your client's MCP configuration file to add the shrink proxy:

Claude Code (~/.claude/settings.json):

{
  "mcp": {
    "caveman-shrink": {
      "type": "local",
      "command": ["npx", "-y", "caveman-shrink", "npx", "@modelcontextprotocol/server-filesystem", "/my/repo"],
      "enabled": true
    }
  }
}

Opencode (~/.config/opencode/opencode.json):

{
  "mcp": {
    "caveman-shrink": {
      "type": "local",
      "command": ["npx", "-y", "caveman-shrink", "npx", "@modelcontextprotocol/server-filesystem", "/my/repo"],
      "enabled": true
    }
  }
}

Restart your client after saving the configuration to load the new MCP server definition.

Environment Variables

Control the middleware behavior using environment variables:

• CAVEMAN_SHRINK_FIELDS – Comma-separated list of fields to compress (default: description)
• CAVEMAN_SHRINK_DEBUG=1 – Outputs compression statistics to stderr

Example with custom fields and debugging:

export CAVEMAN_SHRINK_FIELDS=description,summary
export CAVEMAN_SHRINK_DEBUG=1
caveman --with-mcp-shrink="npx @modelcontextprotocol/server-filesystem /my/project"

Verification and Debugging

Confirm the middleware is active by listing MCP servers in your client:

claude mcp list | grep caveman-shrink

When CAVEMAN_SHRINK_DEBUG=1 is set, you will see output indicating compression ratios:

[caveman-shrink] tools.myTool.description: 342→158 bytes

This confirms that the transformResponse function in src/mcp-servers/caveman-shrink/index.js successfully reduced the payload size before transmission to the model.

Summary

• The --with-mcp-shrink flag in bin/install.js (lines 66-78) provides the fastest path to enable MCP shrink middleware in Caveman by automatically registering the proxy in your client configuration.
• Manual configuration requires adding a caveman-shrink entry to ~/.claude/settings.json or ~/.config/opencode/opencode.json with the command array prefixed by npx -y caveman-shrink.
• Environment variables CAVEMAN_SHRINK_FIELDS and CAVEMAN_SHRINK_DEBUG customize compression targets and enable diagnostic logging from the middleware process.
• Key source files include bin/install.js for installation logic and src/mcp-servers/caveman-shrink/index.js for the compression implementation.

Frequently Asked Questions

What fields does the shrink middleware compress by default?

By default, the middleware only compresses the description field in tool listings. You can modify this behavior by setting the CAVEMAN_SHRINK_FIELDS environment variable to a comma-separated list of field names (e.g., description,summary) before starting the client.

Can I use the shrink middleware with any MCP server?

Yes. The middleware acts as a transparent proxy that works with any upstream MCP server. Simply pass the server's startup command as the value to --with-mcp-shrink, and the installer in bin/install.js will wrap it automatically.

Where does Caveman store the shrink middleware configuration?

The installer writes the configuration to your AI client's standard MCP configuration file. For Claude Code, this is ~/.claude/settings.json; for Opencode, it is ~/.config/opencode/opencode.json. The installMcpShrink function in bin/install.js handles the specific file paths and JSON structure for each supported client.

How do I troubleshoot if compression isn't working?

Set CAVEMAN_SHRINK_DEBUG=1 before running the installer or client. This enables logging in src/mcp-servers/caveman-shrink/index.js that prints the byte reduction for each compressed field. Verify that the caveman-shrink process appears in your MCP server list and that the upstream command tokens are correctly passed in the configuration's command array.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}