Skip to main content

FAQ

Frequently asked questions about mcpzip.

General​

What is mcpzip?

mcpzip is an MCP proxy that aggregates multiple upstream MCP servers and exposes them via a Search + Execute pattern. Instead of loading hundreds of tool schemas into Claude's context window, it gives the model just 3 meta-tools: search_tools, describe_tool, and execute_tool.

This reduces context window usage by 99%+ while maintaining full access to all your tools.

What is MCP?

The Model Context Protocol (MCP) is an open standard created by Anthropic that enables AI assistants to use external tools. It defines how AI clients (like Claude Code) communicate with tool servers.

Key concepts:

  • MCP Server -- a program that exposes tools (functions the AI can call)
  • MCP Client -- the AI application that connects to servers (e.g., Claude Code)
  • Tool -- a function with a name, description, and JSON Schema parameters
  • JSON-RPC -- the message format used for communication
  • tools/list -- the method to discover available tools
  • tools/call -- the method to invoke a specific tool

Learn more: Model Context Protocol Specification

Does mcpzip work with ChatGPT / GPT-4?

mcpzip implements the MCP protocol, which is currently supported by Claude Code and other MCP-compatible clients. It is not a ChatGPT plugin. However, any application that supports MCP can use mcpzip as a tool server.

Is mcpzip open source?

Yes. mcpzip is open source and available on GitHub.

Who built mcpzip?

mcpzip is built by Hypercall.

Setup​

How do I install mcpzip?

The recommended method is from source using Cargo:

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

Or download a pre-built binary from GitHub Releases.

See the Getting Started guide for full instructions.

Do I need to install Rust to use mcpzip?

No. Pre-built binaries are available on the Releases page. Download the binary for your platform and add it to your PATH.

If you want to build from source, you'll need the Rust toolchain (rustup).

How do I add mcpzip to Claude Code?

Add this to your ~/.claude.json:

{
  "mcpServers": {
    "mcpzip": {
      "command": "mcpzip",
      "args": ["serve"]
    }
  }
}

Then restart Claude Code. You should see 3 tools available: search_tools, describe_tool, and execute_tool.

Can I keep some servers connected directly to Claude Code?

Yes. mcpzip doesn't have to manage all your servers. You can have some connected directly and some through mcpzip. For example:

~/.claude.json
{
  "mcpServers": {
    "mcpzip": {
      "command": "mcpzip",
      "args": ["serve"]
    },
    "my-custom-server": {
      "command": "my-server",
      "args": ["start"]
    }
  }
}

Servers connected directly to Claude will have their tools loaded normally. Only the servers in mcpzip's config benefit from context compression.

How It Works​

Does mcpzip modify my tool calls?

No. mcpzip passes tool arguments through to the upstream server unchanged. The only transformation is the tool name: execute_tool("slack__send_message", args) becomes tools/call("send_message", args) on the Slack server.

Arguments are forwarded exactly as-is. mcpzip does not validate, transform, or log the arguments.

What happens if an upstream server is down?
  • During startup: mcpzip serves from its disk cache. The downed server's tools are still searchable and describable (from cache). execute_tool calls to that server will fail with a connection error.
  • During background refresh: If a server fails to connect, its cached tools are preserved. Tools from servers that did connect are updated.
  • During a tool call: mcpzip returns a clear error message. Other servers are unaffected.
Does mcpzip cache tool results?

mcpzip caches search results (query-to-results mapping) and tool schemas (the catalog). It does not cache tool execution results. Every execute_tool call goes to the upstream server in real-time.

Can Claude skip the search step?

Yes. If Claude already knows the tool name (e.g., from a previous search), it can call execute_tool directly without searching first. The search step is for discovery -- once you know the tool name, you can execute it directly.

How does mcpzip handle tool name conflicts?

Tools are namespaced by server using double underscore: slack__send_message, telegram__send_message. Even if two servers expose a tool with the same name, the prefixed names are unique.

Do I need a Gemini API key?

No. Gemini is optional. Without it, mcpzip uses keyword-based search, which works well for direct queries like "slack send message" or "todoist create task".

Gemini adds natural language understanding so you can search with phrases like "help me schedule a meeting" or "post something to the team". It costs ~200-500ms extra latency per search.

Is my tool data sent to Gemini?

When semantic search is used, mcpzip sends a compact representation of your tool catalog to Gemini along with the search query. This includes tool names, descriptions, and parameter summaries -- but not actual data, arguments, or execution results.

The compact format looks like:

slack__send_message: Send a Slack message [channel:string*, text:string*]
todoist__create_task: Create a new task [content:string*, project_id:string]

No credentials, tokens, or user data are sent to Gemini.

Can I use a different LLM for search?

Currently, mcpzip supports Gemini models for semantic search. The model is configurable:

{
  "search": {
    "model": "gemini-2.0-flash"
  }
}

Performance​

How much context does mcpzip save?

With a typical setup of 10 servers and 50 tools per server (500 tools total):

  • Without mcpzip: ~175,000 tokens (500 tools x ~350 tokens each)
  • With mcpzip: ~1,200 tokens (3 meta-tools)
  • Savings: 99.3%

Try the interactive calculator for your specific setup.

Does mcpzip add latency?

The search step adds latency, but context compression reduces it. Net effect:

  • Search (keyword only): < 1ms added
  • Search (with Gemini): 200-500ms added
  • Context processing savings: varies, but typically 100-500ms per message with large tool sets

For most users, the net latency change is neutral or faster because the model processes fewer tokens per message.

How fast does mcpzip start?

mcpzip starts serving in < 5 milliseconds by loading its disk cache. The background refresh to update tools from upstream servers takes 2-10 seconds but runs non-blocking. First-time startup (no cache) waits for at least one server to connect.

Troubleshooting​

mcpzip hangs on startup

mcpzip should never hang -- it serves from cache immediately. If it appears to hang:

  1. Check the config is valid JSON: python3 -m json.tool < ~/.config/compressed-mcp-proxy/config.json
  2. Try with debug logging: RUST_LOG=mcpzip=debug mcpzip serve
  3. Ensure the config has at least one server defined

If the background refresh is slow, mcpzip is still serving. The "hang" might be a slow upstream server.

Claude doesn't see mcpzip's tools
  1. Make sure mcpzip is in your PATH: which mcpzip
  2. Check your Claude Code config has the mcpzip entry:
{
  "mcpServers": {
    "mcpzip": {
      "command": "mcpzip",
      "args": ["serve"]
    }
  }
}
  1. Restart Claude Code
  2. Check for errors: mcpzip serve (run it manually to see errors)
How do I update mcpzip?
# From source
cargo install --git https://github.com/hypercall-public/mcpzip --force

# Or download the latest release binary

Your config, cache, and OAuth tokens are preserved across updates.

See the Troubleshooting page for more detailed solutions.