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

auto

auto:N

auto:5

true

false

Set via environment:

export ENABLE_TOOL_SEARCH=true

Or in settings.json:

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

When to Use Each Setting

auto

true

auto:1

auto

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

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

enabledMcpjsonServers

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

false

Reference

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