---

name: cc-configuring-mcp description: Use when configuring MCP servers in Claude Code, optimizing MCP token usage, troubleshooting MCP connections, understanding Tool Search thresholds, or deciding between MCP tools vs skills for token efficiency

Configuring MCP

Overview

MCP (Model Context Protocol) connects Claude Code to external tools. Core trade-off: MCP tools load at session start (consuming tokens) while skills load on-demand.

Tool Search: Progressive Disclosure for MCP

How It Works

When MCP tool definitions exceed a threshold, Claude Code defers them and uses MCPSearch to discover tools on-demand.

CopyWithout Tool Search: 77K tokens consumed before any work
With Tool Search:    8.7K tokens (85% reduction)

Configuration

Set via environment:

Copyexport ENABLE_TOOL_SEARCH=true

Or in settings.json:

Copy{
  "env": {
    "ENABLE_TOOL_SEARCH": "true"
  }
}

When to Use Each Setting

Per-Tool Control: Not Available

Claude API supports per-tool defer_loading:

Copy// API only - NOT in Claude Code
{
  default_config: { defer_loading: true },
  configs: { "frequently_used_tool": { defer_loading: false } }
}

Claude Code only has global threshold control. Workaround: use rules/instructions to encourage specific MCP tool usage.

Tracking: #12836 (102 upvotes, open)

MCP vs Skills: Token Comparison

Rule of thumb: If you don't use an MCP tool most sessions, either enable Tool Search or use a skill wrapper.

Configuration Files

.mcp.json (Tool Definitions)

Copy{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "package-name"],
      "env": {
        "API_TOKEN": "${API_TOKEN}"
      }
    }
  }
}

settings.json (Enabling Servers)

Copy{
  "enableAllProjectMcpServers": true,
  "enabledMcpjsonServers": ["server-name"]
}

Note: Servers in .mcp.json but not in enabledMcpjsonServers won't load (0 tokens).

Token-Efficient MCP Design

Action Dispatch Pattern

Instead of many tools, use one tool with actions:

Copy// Bad: 23 tools × ~700 tokens each = 16,100 tokens
"linear_create_issue", "linear_update_issue", "linear_search"...

// Good: 1 tool × ~500 tokens
{"action": "create", ...}, {"action": "update", ...}, {"action": "search", ...}

Example: streamlinear (500 tokens vs 17K for official Linear MCP)

Skill Wrappers for Infrequent MCP

For rarely-used MCP servers:

1. Define in .mcp.json but don't enable by default
2. Create skill documenting setup + usage
3. First use: skill instructs to enable + restart

Troubleshooting

MCP Server Not Loading

1. Check enabledMcpjsonServers includes server name
2. Verify env vars are set (use ${VAR} syntax)
3. Test command manually: npx -y package-name

Tool Search Not Activating

Check total MCP token usage vs threshold:

• Default 10% of 200K context = 20K tokens
• If under threshold, set ENABLE_TOOL_SEARCH=true to force

Model Compatibility

Reference

• Claude Code MCP Docs
• Tool Search Announcement
• GitHub #12836 - Per-tool defer_loading request
• GitHub #18303 - Configurable threshold request