mcp-gauge ⚡

See exactly which MCP tools are eating your context window. Disable the deadweight.

MCP tool definitions load into your client context window before any work happens. With a few servers connected, you can burn 30–70% of your context window on tools you've never even called.

mcp-gauge sits between Claude Desktop or Codex and your MCP servers, measures every tool's token cost, tracks which ones you actually use, and lets you disable the rest — live, with one click.

Install

Claude Desktop

npm install -g mcp-gauge
mcp-gauge init

Restart Claude Desktop, then run mcp-gauge status to get your dashboard URL.

Codex

If global npm installs work on your machine:

npm install -g mcp-gauge
mcp-gauge init --client codex

If npm install -g fails with permissions errors, or mcp-gauge is not found after install, use a user-local npm prefix:

mkdir -p ~/.npm-global ~/.npm-cache
npm config set prefix ~/.npm-global
npm install -g --cache ~/.npm-cache mcp-gauge
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
mcp-gauge init --client codex

Restart Codex, then run mcp-gauge status --client codex to get your dashboard URL.

Why global install? mcp-gauge rewrites your client config to point at the proxy binary. If the binary path changes (e.g. npx cache cleared), your MCP access can break silently. A global install keeps the path stable.

What you'll see

⚡ Token Budget: 17,400 / 200,000 (8.7% used by tools)
   Saved: 6,200 tokens by disabling unused tools

  github
    ✓ search_code                              840 tokens  (called 47x)
    ⚠ list_branches                            320 tokens  (never called)
    ✗ get_file_contents                        510 tokens  (disabled)
  slack
    ✓ send_message                             680 tokens  (called 12x)
    ⚠ list_channels                          1,200 tokens  (never called)

For Codex, mcp-gauge also summarizes your local Codex session logs:

Codex Usage (7d)
  Sessions: 22 (22 with token data)
  Processed: 117,592,599 model tokens (cumulative, not context)
  Latest turn: 91,204 tokens
  Latest context: 35% used
  Rate limits: primary 73%, secondary 27%
  Top projects:
    mcp-gauge                            11,264,531 tokens · 1 sessions
  Failure hotspots:
    mcp-gauge                    exec_command       12 failed
  Suggestions:
    - mcp-gauge has repeated exec_command failures; give an exact repo path, ask Codex to inspect first, or narrow the task.

Commands

mcp-gauge init                  # Install into Claude Desktop by default
mcp-gauge init --client codex   # Install into Codex
mcp-gauge status                # Print token budget + dashboard URL in terminal
mcp-gauge status --client codex # Print MCP budget plus compact Codex usage
mcp-gauge codex-usage --days 7  # Detailed Codex usage report from local logs
mcp-gauge telemetry status      # Show opt-in anonymous telemetry status
mcp-gauge telemetry enable      # Enable opt-in anonymous telemetry
mcp-gauge telemetry disable     # Disable anonymous telemetry
mcp-gauge uninstall             # Restore your original Claude Desktop config
mcp-gauge uninstall --client codex

During mcp-gauge init, mcp-gauge asks once whether you want to enable anonymous telemetry. Pressing Enter keeps it off. For scripts and CI, use --telemetry or --no-telemetry:

mcp-gauge init --telemetry
mcp-gauge init --no-telemetry

How it works

mcp-gauge installs itself as a single MCP proxy server in your Claude Desktop or Codex config. When the client starts, it connects to the proxy instead of your real servers directly. The proxy:

1. Spawns all your real MCP servers as normal
2. Measures each tool definition's token cost
3. Filters out tools you've disabled before returning the list to Claude
4. Logs every tool call so you know what's actually being used
5. Serves a local dashboard with live updates

Your real servers run exactly as before. mcp-gauge adds zero latency to tool calls (it's local stdio, not a network hop).

Codex usage tracking

Codex support has two parts:

• MCP proxy tracking: local stdio MCP servers are proxied, measured, and can be disabled from the dashboard.
• Codex log insights: local Codex session logs are read retrospectively to show processed model tokens, context pressure, rate-limit pressure, top projects, expensive sessions, failed tool-call hotspots, and suggestions.

Codex usage tracking works even with zero MCP servers installed. In that case, mcp-gauge status --client codex still reports Codex usage from local logs, and the dashboard shows the Codex Usage section.

This log-based view is read-only and retrospective. It cannot disable built-in Codex tools, app tools, or plugin tools; only proxied MCP tools can be toggled by mcp-gauge.

The processed-token total is cumulative across model calls in the selected window. It is not the same thing as current context size, unique prompt text, or estimated billing.

Adding new MCP servers

After installing mcp-gauge, add the new server in Claude Desktop's settings as usual, then run:

mcp-gauge init

mcp-gauge detects the new server, routes it through the proxy, and removes it from the direct connection so tools don't appear twice. Restart Claude Desktop to apply.

For Codex, add local stdio MCP servers to ~/.codex/config.toml, then run:

mcp-gauge init --client codex

Codex HTTP MCP servers are left untouched because mcp-gauge currently proxies local stdio servers.

Disabling tools

Toggle tools on/off in the dashboard. Changes are saved immediately but take effect after restarting your MCP client — the dashboard shows a notice when a restart is needed.

Uninstall

mcp-gauge uninstall

Restores your Claude Desktop config with all servers you've ever added through mcp-gauge — including ones added after the initial install. Restart Claude Desktop to reconnect directly.

For Codex:

mcp-gauge uninstall --client codex

Privacy

By default, everything stays on your machine. No telemetry, no cloud, no accounts.

mcp-gauge supports opt-in anonymous telemetry so the maintainer can understand real package usage without collecting personal data. During mcp-gauge init, it asks once whether you want to enable telemetry. The default answer is No, and no telemetry is sent unless you opt in.

You can also enable it manually:

mcp-gauge telemetry enable

Telemetry sends only:

• anonymous local install ID
• command name
• package version
• operating system and CPU architecture
• Node.js major version

It does not send prompts, MCP server names, tool names, tool arguments, config files, project paths, usernames, hostnames, or dashboard data. Telemetry uses a short timeout and never fails the mcp-gauge command.

To disable it:

mcp-gauge telemetry disable

For non-interactive installs, use mcp-gauge init --telemetry, mcp-gauge init --no-telemetry, or MCP_GAUGE_NO_TELEMETRY=1.

For development or self-hosted collection, set the collector URL with either:

mcp-gauge telemetry enable --url https://your-collector.example/events

or:

MCP_GAUGE_TELEMETRY_URL=https://your-collector.example/events mcp-gauge status

License

MIT