Claude Code MCP-CLI Experimental Mode - 80% Token Savings

claude-code-mcp-cli-experimental.md

Claude Code MCP-CLI Experimental Mode

Announced December 8, 2025 by Anthropic engineer @catherinewu

The Problem

MCP servers load full tool definitions into the system prompt at session start. Power users with multiple MCPs (supabase, tabz, shadcn, docker-mcp, etc.) can burn 40-50k tokens before typing anything.

The Solution

export ENABLE_EXPERIMENTAL_MCP_CLI=true

This enables on-demand MCP tool loading via mcp-cli commands instead of upfront.

Real-World Results

Metric	Before	After
Context used at start	63% (126k/200k)	11% (21k/200k)
MCP tools tokens	43.8k	0 (on-demand)
Free space	74k (37%)	179k (89%)

~105k tokens reclaimed for actual work.

How It Works

Instead of loading all tool schemas upfront, Claude uses bash commands:

# Get tool info on-demand
mcp-cli info supabase/list_tables

# Execute the tool
mcp-cli call supabase/list_tables '{}'

Large outputs can be piped to files via jq, keeping bulky data out of context.

Setup

Permanent (recommended)

# Bash
echo 'export ENABLE_EXPERIMENTAL_MCP_CLI=true' >> ~/.bashrc
source ~/.bashrc

# Zsh
echo 'export ENABLE_EXPERIMENTAL_MCP_CLI=true' >> ~/.zshrc
source ~/.zshrc

# Fish
echo 'set -gx ENABLE_EXPERIMENTAL_MCP_CLI true' >> ~/.config/fish/config.fish

Per-session

ENABLE_EXPERIMENTAL_MCP_CLI=true claude

Verify It's Working

Run /context in Claude Code. You should see:

• No "MCP tools" section (or minimal tokens)
• Much higher "Free space" percentage

Revert If Needed

# Disable for one session
ENABLE_EXPERIMENTAL_MCP_CLI=false claude

# Or remove from shell config
# Delete the export line from ~/.bashrc

References

• GitHub Issue #12836 - Original feature request
• Anthropic Announcement Comment - catherinewu's announcement

Status

⚠️ Experimental - No official docs yet. Works as of Claude Code v2.0.62 (Dec 2025).

Super helpful - has saved me and several coworkers a lot of tokens while increasing response quality.
Thank you 😄