---
name: mcp-tool-search
description: |
  Dynamic MCP tool discovery and lazy loading for context optimization.
  Use when working with MCP servers, optimizing context usage, or
  dynamically loading tools. Implements the auto:N syntax for threshold
  control and reduces MCP tool context consumption.

user-invocable: false
---

# MCP Tool Search Skill

## Purpose

MCP tools can consume 8-30% of your context window just by being registered, even when unused. This skill documents how to use Claude Code's MCP Tool Search feature to dynamically load tools only when needed.

## The Problem

```
Without lazy loading:
- Browser automation tools: ~20% context
- GitHub MCP server: ~15% context
- Multiple servers: Can exceed 50% context before you start working
```

## Solution: MCP Tool Search

Claude Code v2.0+ includes MCP Tool Search, which:
1. Detects when MCP tool descriptions exceed 10% of context
2. Replaces preloaded tools with a search interface
3. Dynamically loads only the tools you need

## Configuration

### Auto-Enable Threshold

Configure in `~/.claude/settings.json`:

```json
{
  "mcpToolSearch": "auto:10"
}
```

The `auto:N` syntax sets the context percentage threshold:
- `auto:10` - Enable when MCP tools exceed 10% context (default)
- `auto:5` - More aggressive, enables at 5%
- `auto:0` - Always use tool search
- `false` - Disable tool search (preload all tools)

### Per-Server Configuration

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "lazyLoad": true
    },
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem"],
      "lazyLoad": false
    }
  }
}
```

## How Tool Search Works

1. **Detection**: Claude Code measures total MCP tool description tokens
2. **Threshold Check**: If exceeds `auto:N` percentage, enables search mode
3. **Search Interface**: Claude can issue `mcp_tool_search(query)` to find tools
4. **Dynamic Loading**: Matched tools load into context on demand
5. **Multiple Searches**: Claude can refine queries or make parallel searches

## Tool Naming Convention

MCP tools follow the pattern: `mcp__<server>__<tool>`

Examples:
- `mcp__github__search_repositories`
- `mcp__filesystem__read_file`
- `mcp__memory__create_entities`

## Best Practices

### 1. Monitor Context Usage

Use `/context` command to check MCP overhead:

```
/context
```

Look for warnings about excluded skills due to MCP tools.

### 2. Set Appropriate Thresholds

| Use Case | Threshold | Rationale |
|----------|-----------|-----------|
| Many MCP servers | `auto:5` | Aggressive optimization |
| Few MCP servers | `auto:15` | Balance convenience |
| Single server | `false` | Preload is fine |

### 3. Optimize Server Descriptions

MCP server authors should:
- Keep tool descriptions concise
- Use clear, searchable names
- Group related tools logically

## Integration with Genesis

### Checking MCP Status

```bash
# List registered MCP servers
claude /mcp

# Check which tools are loaded
claude --debug
```

### Genesis MCP Servers

Genesis uses these MCP servers:
- `mcp__ghl__*` - GoHighLevel integration
- `mcp__memory__*` - Memory persistence
- `mcp__sequential-thinking__*` - Reasoning chains

Configure in `/mnt/e/genesis-system/mcp-config.json`.

## Troubleshooting

### Tools Not Found

If Claude can't find expected tools:
1. Check server is running: `/mcp`
2. Verify tool name spelling
3. Try broader search terms
4. Check server logs for errors

### High Context Usage

If context still high with lazy loading:
1. Reduce number of MCP servers
2. Use more aggressive threshold
3. Check for non-MCP context consumers

## References

- [Claude Code MCP Documentation](https://code.claude.com/docs/en/mcp)
- [MCP Tool Search Feature](https://analyticsindiamag.com/ai-news-updates/claude-code-finally-fixes-the-huge-issue-with-mcps/)
- Genesis MCP Config: `/mnt/e/genesis-system/mcp-config.json`
