What Are the Different Proxy Modes Available in Caveman?

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 and the source tree.

Default Mode: No Proxy

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

In bin/install.js (lines 90–94), the default behavior omits any proxy wrapper:

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:

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, 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. The flag parsing and documentation appear in 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:

# 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 (lines 18–27). Documentation exists in 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 — 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 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 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 documents current usage.

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