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

Set via environment:

export ENABLE_TOOL_SEARCH=true

Or in settings.json:

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

When to Use Each Setting

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

Reference

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