# What Are the Different Proxy Modes Available in Caveman?

> Explore Caveman's three proxy modes: default, MCP-shrink, and legacy HTTP proxy. Learn how to optimize your caching with these flexible options.

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

---

**Caveman supports three proxy modes: default (no proxy), MCP-shrink proxy via `--with-mcp-shrink`, and legacy HTTP proxy via the `caveman-proxy` binary.**

The Caveman command-line tool offers flexible networking configurations for running Model Context Protocol (MCP) scripts. Whether you need direct execution, intelligent response compression, or traditional HTTP forwarding, Caveman's proxy modes handle different deployment scenarios. Each mode is implemented as a distinct binary or flag combination, documented in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) and the source tree.

## Default Mode: No Proxy

Running Caveman without any proxy flags executes scripts directly against MCP servers.

In [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) (lines 90–94), the default behavior omits any proxy wrapper:

```bash
caveman-cli run my-script.mjs

```

This mode is ideal when:
- You control the upstream MCP server directly
- Response size is not a concern
- You want minimal overhead

## MCP-Shrink Proxy Mode

The **MCP-shrink proxy** compresses verbose MCP responses by intercepting and rewriting list operations.

Enable it with the `--with-mcp-shrink` flag followed by your upstream server command:

```bash
caveman-cli --with-mcp-shrink="npx @modelcontextprotocol/server-filesystem /tmp" run my-script.mjs

```

### How MCP-Shrink Works

According to [`src/mcp-servers/caveman-shrink/README.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/README.md), the proxy:
- Spawns the upstream MCP server as a child process
- Intercepts `tools/list`, `prompts/list`, and `resources/list` responses
- Compresses prose fields (descriptions, documentation) using Caveman's compression rules

The implementation lives in [`src/mcp-servers/caveman-shrink/index.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/index.js). The flag parsing and documentation appear in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) (lines 92–100).

Use this mode when:
- Upstream servers return bloated descriptions
- Token limits are a concern
- You want automatic compression without modifying server code

## Legacy HTTP Proxy Mode

The **legacy HTTP proxy** provides standard HTTP/HTTPS forwarding compatible with conventional proxy environments.

Unlike the integrated MCP-shrink flag, this mode runs as a separate binary:

```bash

# Start the proxy

caveman-proxy --port 8080 &

# Configure environment variables

export HTTP_PROXY="http://localhost:8080"
export HTTPS_PROXY="http://localhost:8080"

# Run Caveman normally

caveman-cli run my-script.mjs

```

The `caveman-proxy` binary is installed automatically alongside `caveman-cli`, as listed in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) (lines 18–27). Documentation exists in [`src/proxy/README.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/proxy/README.md).

This mode suits:
- Corporate environments with mandatory `HTTP_PROXY` variables
- Existing infrastructure expecting standard proxy behavior
- Backward compatibility with older Caveman versions

## Choosing Between Proxy Modes

| Scenario | Recommended Mode | Command Pattern |
|----------|---------------|-----------------|
| Direct MCP execution | No proxy (default) | `caveman-cli run script.mjs` |
| Compress verbose responses | MCP-shrink proxy | `caveman-cli --with-mcp-shrink="<cmd>" run script.mjs` |
| Standard HTTP proxy support | Legacy HTTP proxy | `caveman-proxy --port 8080` + env vars |

## Implementing Custom Proxy Logic

If Caveman's built-in modes insufficient, examine the source implementations:

- **[`src/mcp-servers/caveman-shrink/index.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/index.js)** — template for MCP-intercepting proxies
- **`src/proxy/`** — HTTP proxy foundation

Both follow the proxy-in-proxy contract established in earlier Caveman versions.

## Summary

- **Default mode** runs Caveman without proxy overhead—best for controlled environments
- **MCP-shrink proxy** (`--with-mcp-shrink`) compresses MCP list responses automatically via `caveman-shrink`
- **Legacy HTTP proxy** (`caveman-proxy` binary) provides standard `HTTP_PROXY` compatibility
- All three modes are documented in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) and installed automatically

## Frequently Asked Questions

### What is the MCP-shrink proxy used for?

The MCP-shrink proxy reduces token consumption by compressing verbose description fields in MCP `tools/list`, `prompts/list`, and `resources/list` responses. It wraps upstream servers transparently, requiring no server modifications.

### Can I use multiple proxy modes simultaneously?

No. Caveman does not support stacking proxy modes. Choose one: default execution, MCP-shrink for compression, or legacy HTTP proxy for environment compatibility. The `caveman-proxy` binary can run independently, but `--with-mcp-shrink` expects direct execution.

### Where is the proxy mode configured?

Proxy mode selection happens at the command line. The [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) file (lines 18–27, 90–100) parses flags and registers binaries. No configuration file changes are required—flags are evaluated per-invocation.

### Is the legacy HTTP proxy deprecated?

The term "legacy" refers to backward compatibility, not deprecation. The `caveman-proxy` binary remains actively maintained for environments requiring standard HTTP proxy variables. The README in [`src/proxy/README.md`](https://github.com/JuliusBrussee/caveman/blob/main/src/proxy/README.md) documents current usage.