Startup Time: Instant​

The most important performance metric for a CLI tool is startup time. mcpzip starts serving in under 5 milliseconds.

How? Disk caching. On startup, mcpzip:

1. Reads ~/.config/compressed-mcp-proxy/cache/tools.json (typically 100KB-2MB)
2. Deserializes the tool catalog into memory
3. Starts the MCP server on stdio

No network connections. No process spawning. Just read a file and serve.

The background refresh runs concurrently -- it connects to all upstream servers in parallel, calls tools/list on each, and merges the results into the catalog. This takes 2-10 seconds depending on your servers, but it never blocks a request.

Search Latency​

mcpzip's search engine is the heart of the proxy. It needs to be fast because Claude calls it on nearly every tool interaction.

Keyword Search: under 1ms​

The keyword search engine tokenizes the query and scores it against tool metadata. It runs entirely in memory with no I/O.

LLM Search: 200-500ms​

When Gemini is configured, mcpzip sends the query and a compact tool catalog to the Gemini API. Latency depends on:

• Network round-trip to Gemini (~50-100ms)
• Gemini inference time (~100-300ms)
• Response parsing (~1ms)

Query Cache: under 0.1ms​

Repeated or similar queries hit the cache. Cache keys are normalized (lowercased, tokenized, sorted) so "slack send message" and "send message slack" are the same cache entry.

Combined Flow​

On a cache miss with Gemini enabled:

1. Keyword search runs immediately: under 1ms
2. LLM search runs in parallel: 200-500ms
3. Results are merged and cached: under 1ms

Total: 200-500ms (dominated by LLM network latency)

On a cache hit: under 0.1ms

Memory Footprint​

mcpzip is designed to be lightweight. It runs as a child process of Claude Code, so every megabyte matters.

*stdio connections spawn child processes (e.g., npx @anthropic/slack-mcp). Those processes have their own memory, typically 30-100MB each. The ~20MB figure is mcpzip itself, not including the child processes.

Why So Small?​

1. No garbage collector -- Rust uses compile-time memory management. No GC pauses, no overhead.
2. No runtime -- Rust compiles to native code. No JVM, no V8, no interpreter.
3. Compact data structures -- Tool entries use String and serde_json::Value, not heavyweight ORM objects.
4. Lazy connections -- Upstream connections are created on first use, not at startup.

Binary Size: 5.8MB​

The Rust binary is statically linked with musl libc on Linux, meaning it runs on any Linux distribution without installing runtime dependencies. On macOS, it links against system libraries.

What is in the binary?​

• Tokio async runtime (~1.5MB)
• HTTP client (reqwest) (~1MB)
• JSON parser (serde_json) (~0.3MB)
• MCP protocol implementation (~0.5MB)
• CLI framework (clap) (~0.3MB)
• Business logic (~0.5MB)
• Other dependencies (~1.7MB)

Connection Pooling​

mcpzip maintains a connection pool with lazy initialization and idle reaping.

Lazy Connects​

Connections are created on first use. If you have 10 servers configured but only use 3, only 3 connections are created.

Idle Timeout​

Idle connections are closed after 5 minutes (configurable). This is important for stdio connections, which are full OS processes consuming resources.

Concurrent Startup​

During catalog refresh, all servers are connected in parallel with a 30-second per-server timeout. A slow server does not block the others.

Reconnection​

If a connection drops (process crashes, network error), it is automatically re-established on the next execute_tool call. No manual intervention needed.

Tool Call Latency​

The overhead mcpzip adds to a tool call is minimal:

The total overhead is under 0.3ms. Tool call latency is entirely dominated by the upstream server's execution time, not mcpzip.

Summary​

mcpzip is designed to be invisible. It starts instantly, searches in milliseconds, and adds negligible overhead to tool calls. The only thing you notice is that your context window is 99% larger.

mcpzip is open source at github.com/hypercall-public/mcpzip. Built by Hypercall.

The Problem​

Every MCP tool has a JSON Schema that describes its parameters. When Claude Code connects to an MCP server, it calls tools/list and loads every tool schema into the context window. This happens on every message.

A typical tool schema looks like this:

{
  "name": "send_message",
  "description": "Send a message to a Slack channel or direct message",
  "inputSchema": {
    "type": "object",
    "properties": {
      "channel": {
        "type": "string",
        "description": "Channel ID or name (e.g., #general or C01234567)"
      },
      "text": {
        "type": "string",
        "description": "The message text, supports Slack markdown"
      },
      "thread_ts": {
        "type": "string",
        "description": "Thread timestamp to reply in a thread"
      },
      "unfurl_links": {
        "type": "boolean",
        "description": "Whether to unfurl URLs"
      }
    },
    "required": ["channel", "text"]
  }
}

This single tool consumes ~350 tokens. Now multiply.

The Math​

With Claude's 200K context window, a heavy setup uses 87.5% of the context just for tool schemas. A power setup exceeds the context window entirely.

With mcpzip​

mcpzip replaces all tool schemas with exactly 3 meta-tools:

The savings:

Try It Yourself​

Why This Matters​

1. More Room for Conversation​

Every token spent on tool schemas is a token you cannot use for your actual conversation. With 500 tools consuming 175K tokens, you have only 25K tokens left for your prompt, conversation history, and model output. That is barely enough for a meaningful interaction.

2. Faster Responses​

More context tokens means more processing time. The model has to read and attend to all those tool schemas on every message, even if it is not going to use any of them. Fewer tokens means faster inference.

3. Better Tool Selection​

Research and practical experience show that LLMs make worse tool choices when presented with too many options. With 500 tools, the model might:

• Pick a similar but wrong tool
• Hallucinate parameters from a different tool
• Fail to find the right tool entirely

With 3 meta-tools and on-demand search, Claude gets exactly the tools it needs, when it needs them.

4. No Hard Limits​

Some models cap the number of tools they can handle. GPT-4 starts degrading noticeably past ~60 tools. By compressing everything behind 3 meta-tools, mcpzip removes this limit entirely.

The Compact Representation​

When mcpzip returns search results, it uses a compact format that is ~7x smaller than full JSON schemas:

slack__send_message: Send a Slack message [channel:string*, text:string*]
todoist__create_task: Create a new task [content:string*, project_id:string]
github__create_issue: Create a GitHub issue [title:string*, body:string]

Each line is ~50 tokens instead of ~350 tokens. The * marks required parameters. Claude gets enough information to decide which tool to use and can optionally call describe_tool for the full schema if it needs more detail.

Getting Started​

# Install
cargo install --git https://github.com/hypercall-public/mcpzip

# Migrate from existing Claude Code config
mcpzip migrate --dry-run  # preview
mcpzip migrate             # do it

# Restart Claude Code

That is it. Your existing MCP servers keep working, but now they are behind mcpzip's 3 meta-tools instead of flooding the context window.

mcpzip is open source at github.com/hypercall-public/mcpzip. Built by Hypercall.

So we rewrote the entire thing in Rust. Here is why, and how it went.

The Numbers​

The Rust version is 47% smaller as a binary, has 4x more tests, and uses fewer files despite being more code (because test code is colocated with source in Rust).

Why Rewrite?​

1. Binary Size​

Go's runtime and garbage collector add a fixed overhead. Our Go binary was 11MB -- not huge, but unnecessary for what is essentially a proxy. The Rust binary is 5.8MB with zero runtime overhead.

For a tool that gets installed on developer machines and runs as a child process of Claude Code, every megabyte matters.

2. Memory Usage​

Go's garbage collector means unpredictable memory spikes during catalog refresh. With 500+ tools and 10+ upstream connections, these spikes were noticeable. Rust's ownership model gives us predictable, low memory usage.

3. Concurrency Model​

mcpzip needs careful concurrency: multiple upstream connections, parallel search strategies, background catalog refresh, and real-time tool calls -- all at once.

Go's goroutines are lightweight, but sharing mutable state requires careful channel choreography or mutex discipline. Rust's type system enforces correct concurrency at compile time:

Go version -- runtime race detection:

type Catalog struct {
    mu    sync.RWMutex
    tools map[string]*ToolEntry
    path  string
}

func (c *Catalog) GetTool(name string) (*ToolEntry, bool) {
    c.mu.RLock()
    defer c.mu.RUnlock()
    t, ok := c.tools[name]
    return t, ok
}

Rust version -- compile-time safety:

pub struct Catalog {
    tools: RwLock<HashMap<String, ToolEntry>>,
    cache_path: PathBuf,
}

impl Catalog {
    pub fn get_tool(&self, name: &str) -> Option<ToolEntry> {
        let tools = self.tools.read().unwrap();
        tools.get(name).cloned()
    }
}

Both use a RwLock, but Rust's borrow checker ensures you cannot forget to acquire the lock or accidentally access the data without it. In Go, nothing stops you from accessing c.tools directly -- you rely on discipline and race detectors to catch mistakes.

4. Error Handling​

Go's if err != nil pattern is verbose but workable. Rust's Result and ? operator give us the same explicit error handling with less boilerplate:

Go:

func (c *Catalog) Load() error {
    data, err := os.ReadFile(c.path)
    if err != nil {
        return fmt.Errorf("load catalog: %w", err)
    }
    var tools map[string]*ToolEntry
    if err := json.Unmarshal(data, &tools); err != nil {
        return fmt.Errorf("parse catalog: %w", err)
    }
    c.mu.Lock()
    c.tools = tools
    c.mu.Unlock()
    return nil
}

Rust:

pub fn load(&self) -> Result<(), McpzipError> {
    let data = std::fs::read_to_string(&self.cache_path)?;
    let tools: HashMap<String, ToolEntry> = serde_json::from_str(&data)?;
    *self.tools.write().unwrap() = tools;
    Ok(())
}

Same logic, half the code. The ? operator propagates errors automatically, and the From trait handles error type conversion.

What Was Preserved​

The Rust rewrite is a faithful port. Everything that worked in Go works the same way in Rust:

• Same config format -- your config.json works without changes
• Same 3 meta-tools -- search_tools, describe_tool, execute_tool
• Same architecture -- ProxyServer, Catalog, Manager, Searcher
• Same search algorithm -- keyword + Gemini orchestrated search
• Same OAuth flow -- PKCE, browser callback, token persistence
• Same CLI -- serve, init, migrate with the same flags
• Same file locations -- ~/.config/compressed-mcp-proxy/

If you were using the Go version, the Rust version is a drop-in replacement.

What Improved​

Beyond the raw performance numbers, several things got better:

Background Catalog Refresh​

The Go version refreshed the catalog synchronously on startup. The Rust version loads from disk cache immediately and refreshes in the background. First request is served in under 5ms instead of waiting for all servers to connect.

SSE Parsing​

The Rust version uses a more robust SSE parser that handles edge cases in multi-line data: fields and reconnection.

OAuth Token Reuse​

The Rust version checks for mcp-remote tokens in addition to its own, so you do not have to re-authenticate if you have already used mcp-remote with the same server.

Test Coverage​

We went from ~60 tests to 240+. Every module has comprehensive unit tests, including edge cases like:

• Nullable JSON types ("type": ["string", "null"])
• anyOf schemas
• Double-underscore tool name parsing
• Config validation (missing commands, invalid types)
• Token refresh and expiration

The Claude Code Experience​

Both the Go and Rust versions were written with Claude Code. The rewrite was a fascinating exercise in using an AI coding assistant for a major port:

1. We fed Claude the Go codebase and the MCP specification
2. Claude generated Rust modules matching the Go architecture
3. We iteratively refined the code with Claude, adding tests and fixing edge cases
4. The entire rewrite took about a day of wall-clock time

The tight feedback loop -- write code, run tests, fix issues -- works exceptionally well with Claude Code. Having 240+ tests pass gives high confidence that the port is correct.

Should You Rewrite Your Project?​

Probably not. Rewrites are risky and usually not worth it. We did it because:

1. mcpzip is relatively small (~6K LOC)
2. The architecture was clean and well-understood
3. We had specific, measurable goals (binary size, memory, test coverage)
4. We had 60+ tests as a safety net for the port

If your project is larger, consider incremental improvements instead. But if you are starting fresh and care about binary size, memory usage, and compile-time safety, Rust is an excellent choice for CLI tools and proxies.

mcpzip is open source at github.com/hypercall-public/mcpzip. Built by Hypercall.