shield_lock
JinDaGe
← Back to skills
extension
Category: AI Agent CapabilitiesNo API key required

cc-configuring-mcp

Use when optimizing MCP token usage, understanding Tool Search thresholds, or deciding MCP vs skills for token efficiency. For plugin MCP bundling, use plugin-dev:mcp-integration.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

Configuring MCP

Scope

This skill covers MCP token optimization and Tool Search. For different purposes, use:

  • Bundling MCP in plugins: plugin-dev:mcp-integration
  • This skill: Token efficiency, Tool Search thresholds, skill wrappers for infrequent 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.

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

Configuration

| Value | Behavior | | -------- | --------------------------------------- | | auto | Activates at 10% of context (default) | | auto:N | Activates at N% (e.g., auto:5 for 5%) | | true | Always use Tool Search | | false | Never use Tool Search |

Set via environment:

export ENABLE_TOOL_SEARCH=true

Or in settings.json:

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

When to Use Each Setting

| Scenario | Recommended | | ------------------------------------ | ------------------------------- | | Use MCP tools every session | auto (default) | | Use MCP tools occasionally | true or auto:1 | | Many MCP servers (50+ tools) | auto (triggers automatically) | | Few MCP servers, want to save tokens | true |

Per-Tool Control: Not Available

Claude API supports per-tool defer_loading:

// 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

| Aspect | MCP (under threshold) | MCP (Tool Search) | Skill | | ----------- | --------------------- | ----------------------- | -------------------- | | Load timing | Session start | On-demand via search | On-demand via invoke | | Base cost | Full tool definitions | ~500 tokens (MCPSearch) | 0 tokens | | Use cost | 0 (already loaded) | Tool definitions loaded | Skill content loaded | | Best for | Frequent use | Occasional use | Rare use |

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)

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

settings.json (Enabling Servers)

{
  "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:

// 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

| Model | Tool Search Support | | --------- | ------------------- | | Opus 4+ | Yes | | Sonnet 4+ | Yes | | Haiku | No (use false) |

Reference