MCP Mode

Progressive MCP for Claude Code. Zero Token Tax.

Access MCP tools on-demand without loading schemas into your context window.

Quick Start · Commands · Configuration · Troubleshooting

Note: See SECURITY.md for known limitations and security considerations.

What is MCP Mode?

MCP Mode lets you use MCP (Model Context Protocol) servers from Claude Code without the massive token cost that comes from auto-injecting tool schemas into your context window.

The Token Tax

When you configure MCP servers in Claude Code's native config files (~/.claude.json or .mcp.json), all tool schemas are loaded into context at session startup. This "token tax" consumes 30-50%+ of available tokens before any conversation begins. Real-world reports show 66,000+ tokens consumed at startup (33% of 200k context).

Every MCP tool you add increases this tax. The more capable your setup, the less context you have for actual work.

Zero-Overhead Access

MCP Mode eliminates this tax entirely by using separate config files (~/.claude/mcp.json) that Claude Code doesn't see. Servers are connected on-demand via CLI, schemas loaded only when needed, and tool calls executed outside the context window.

Result: Full context available for actual work. Access any number of MCP tools with zero startup cost.

Installation

# Initialize in your project
npx mcp-mode init

# Or install globally
npm install -g mcp-mode
mcp-mode init

This creates .claude/skills/mcp-mode/ with the skill files.

Quick Start

For Claude Desktop Users (macOS)

If you already have MCP servers configured in Claude Desktop, import them instantly:

# See what servers are available to import
.claude/skills/mcp-mode/bin/cm import --from desktop --dry-run

# Import all your servers
.claude/skills/mcp-mode/bin/cm import --from desktop

# Import specific servers only
.claude/skills/mcp-mode/bin/cm import --from desktop firecrawl Tavily

For New Users

Create your config file at ~/.claude/mcp.json:

{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "my-mcp-server"],
      "env": {}
    }
  }
}

Verify it works:

.claude/skills/mcp-mode/bin/cm servers
.claude/skills/mcp-mode/bin/cm doctor --server my-server

Using MCP Mode in Claude Code

Just tell Claude what you want to do. The skill handles the rest.

Example Prompts

Discovery

"What MCP servers do I have available?"

"Show me the tools on my firecrawl server"

"Find any tools related to web scraping"

Execution

"Scrape the homepage of https://example.com"

"Search for documentation about authentication"

"Get me the contents of that GitHub repo"

Setup

"Import my MCP servers from Claude Desktop"

"Check if my firecrawl connection is working"

"Start the MCP daemon for faster calls"

Example Conversation

You: What MCP tools do I have for web scraping?

Claude: Let me check your MCP servers... You have 'firecrawl' configured 
with 8 tools including scraping, crawling, and mapping capabilities.
What would you like to scrape?

You: Grab the main content from https://docs.anthropic.com

Claude: [scrapes page via MCP Mode]
Here's the content from the Anthropic docs...

The skill translates your intent into the right cm commands automatically.

Command Reference

All commands use the cm CLI. Call with full path:

Workspace: ./.claude/skills/mcp-mode/bin/cm
Personal: ~/.claude/skills/mcp-mode/bin/cm

Discovery Commands

Command	Purpose
`cm servers [--json]`	List all configured MCP servers
`cm index --server <name> [--refresh] [--json]`	List tools on a server
`cm search "<query>" --server <name> [--limit N] [--refresh] [--json]`	Search tools by keyword
`cm doctor --server <name> [--no-connect] [--json]`	Test server connection and show config

Execution Commands

Command	Purpose
`cm call <tool> --server <name> [--args '{}'] [--args-file path.json] [--json] [--no-daemon]`	Execute a single tool
`cm hydrate <tool1> <tool2> ... --server <name> [--out <dir>] [--refresh] [--json]`	Get full schemas + TypeScript types
`cm run --workflow <file.js> --tools <a,b,...> --server <name> [--retries N] [--timeout-ms N]`	Run multi-tool workflow

Import Command

Command	Purpose
`cm import --from desktop [--dry-run] [--scope user\|project]`	Import all servers from Claude Desktop
`cm import --from desktop <server1> <server2> ...`	Import specific servers

Daemon Commands (Faster Calls)

The daemon keeps MCP connections alive for ~5x faster tool calls.

Command	Purpose
`cm daemon start`	Start background daemon for current project
`cm daemon stop`	Stop current project's daemon
`cm daemon status [--json]`	Show daemon status and connections
`cm daemon status --all`	List all running daemons across projects
`cm daemon list`	Alias for `status --all`
`cm daemon warm [<server>]`	Pre-warm server connection(s)

Configuration Commands

Command	Purpose
`cm config <server> autoWarm true\|false`	Enable/disable auto-warm for a server

Configuration

Config File Locations

Config	Path	Purpose
User	`~/.claude/mcp.json`	Personal MCP servers (all projects)
Project	`<project>/.claude/mcp.json`	Project-specific servers

CRITICAL: Do NOT use Claude Code's native configs (~/.claude.json, .mcp.json) for servers you want to access via MCP Mode. Those will be auto-injected into context, defeating the purpose.

Config Format

stdio Server (runs a local command)

{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "env": {
        "SOME_API_KEY": "your-key-here"
      }
    }
  }
}

HTTP Server (connects to a URL)

{
  "mcpServers": {
    "remote-server": {
      "type": "http",
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

Importing from Claude Desktop (macOS)

If you use Claude Desktop, you likely already have MCP servers configured. Import them:

# Preview what would be imported
cm import --from desktop --dry-run

# Import all servers to user config (~/.claude/mcp.json)
cm import --from desktop

# Import specific servers
cm import --from desktop firecrawl Tavily

# Import to project config instead
cm import --from desktop --scope project

Advanced Usage

Manual Connection Overrides

Connect to servers without configuring mcp.json:

# HTTP server
cm call my_tool --http-url "https://mcp.example.com/sse" --headers-json '{"Authorization":"Bearer xxx"}'

# stdio server  
cm call my_tool --stdio-command "node" --stdio-args "server.js,--port,3000" --env-json '{"API_KEY":"xxx"}'

JSON Output Mode

Most commands support --json for programmatic use:

cm servers --json
cm index --server X --json
cm call tool --server X --json
cm daemon status --json

Workflow Engine

For complex multi-tool orchestration, use workflow files:

// workflow.js
workflow = async () => {
  const results = await t.searchDocuments({ query: "API", limit: 5 });
  const ids = results.map(r => r.id);
  const docs = await Promise.all(ids.map(id => t.getDocument({ id })));
  return docs;
}

cm run --server myserver --tools search_documents,get_document --workflow workflow.js

Note: Tool names use snake_case in CLI but camelCase in workflow code (search_documents → t.searchDocuments).

Cache and Artifacts

All MCP Mode data is stored in .claude/mcp-mode/:

Path	Content
`cache/<server>/tools.json`	Cached tool inventory
`hydrated/<server>/<timestamp>/`	Full schemas + TypeScript types
`runs/<server>/<timestamp>/run.json`	Workflow execution traces

Troubleshooting

Issue	Solution
`command not found: cm`	Use full path: `./.claude/skills/mcp-mode/bin/cm`
`Permission denied`	Run `chmod +x .claude/skills/mcp-mode/bin/cm`
`Server not found`	Check `cm servers` and verify `~/.claude/mcp.json` exists
`Connection timeout`	Run `cm doctor --server X` to diagnose
`Tool not found`	Run `cm index --server X --refresh` to refresh cache
`Daemon not starting`	Check for port conflicts, try `cm daemon stop` first
`Import finds no servers`	Ensure Claude Desktop is installed and has MCP servers configured

How It Works

flowchart TB
    subgraph claude["Claude Code Session"]
        context["Context Window (200k tokens)<br/><br/>Your conversation + code<br/>(NOT filled with MCP schemas!)"]
        cm["cm call / cm run"]
        context --> cm
    end
    
    config["~/.claude/mcp.json<br/>(MCP Mode config)<br/><i>Invisible to Claude Code</i>"]
    servers["MCP Server(s)<br/>(connected on-demand)"]
    
    cm --> config
    config --> servers

Related Projects

Droid Mode - The Factory.ai version MCP Mode was ported from
MCP Specification - The Model Context Protocol

Experimental Status

This is experimental software (v0.x)

MCP Mode is under active development. The API may change between versions.

Feedback welcome! Open an issue on GitHub.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.github/workflows		.github/workflows
src		src
templates/skills/mcp-mode		templates/skills/mcp-mode
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Folders and files

Latest commit

History

Repository files navigation

MCP Mode

What is MCP Mode?

The Token Tax

Zero-Overhead Access

Installation

Quick Start

For Claude Desktop Users (macOS)

For New Users

Using MCP Mode in Claude Code

Example Prompts

Example Conversation

Command Reference

Discovery Commands

Execution Commands

Import Command

Daemon Commands (Faster Calls)

Configuration Commands

Configuration

Config File Locations

Config Format

stdio Server (runs a local command)

HTTP Server (connects to a URL)

Importing from Claude Desktop (macOS)

Advanced Usage

Manual Connection Overrides

JSON Output Mode

Workflow Engine

Cache and Artifacts

Troubleshooting

How It Works

Related Projects

Experimental Status

License

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages