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

> Enable MCP shrink middleware in Caveman effortlessly. Use the installer flag to compress text fields, reducing token usage without code changes. Learn how now.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: how-to-guide
- Published: 2026-07-07

---

**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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```json
"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`](https://github.com/JuliusBrussee/caveman/blob/main/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:

```bash
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`):

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

```

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

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

```bash
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:

```bash
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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) for installation logic and [`src/mcp-servers/caveman-shrink/index.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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.