MCP Management

Manage and interact with Model Context Protocol (MCP) servers. Discover capabilities, analyze tools/prompts/resources, and execute via subagents — without polluting the main context window.

Key Benefits

• Progressive disclosure of MCP capabilities (load only what's needed)
• Intelligent tool/prompt/resource selection based on task requirements
• Multi-server management from a single config file
• Context-efficient: subagents handle MCP discovery and execution
• Persistent tool catalog: discovered tools saved to JSON for fast reference

When to Use

1. Discover MCP capabilities — list available tools/prompts/resources
2. Task-based tool selection — analyze which MCP tools fit a specific task
3. Execute MCP tools — call tools programmatically with proper parameter handling
4. MCP integration — build or debug MCP client implementations
5. Context management — delegate MCP operations to subagents to keep main context clean

Configuration

MCP servers are configured in .claude/.mcp.json. Per-server setup details (Gemini CLI integration, custom response formats) live in references/configuration.md and references/gemini-cli-integration.md. The MCP protocol reference is in references/mcp-protocol.md.

Core Scripts

# Analyze MCP tools — capability summary, token counts, server status
node ./scripts/cli.ts analyze-tools --input ./assets/tools.json

# Call a tool (uses cached capability map, no main-context pollution)
node ./scripts/cli.ts call --server <name> --tool <name> --args '<json>'

# Discover tools from a live server, save to ./assets/tools.json
node ./scripts/cli.ts discover --server <name> --output ./assets/tools.json

The MCP client implementation is in scripts/mcp-client.ts; the CLI wrapper is in scripts/cli.ts. Run npm install in scripts/ first.

Workflow

1. Discover — list configured servers, fetch their tools/prompts/resources
2. Analyze — match capabilities to the task, surface only the relevant subset
3. Execute — call the matched tool with the right parameters
4. Report — return structured JSON {server, tool, success, result, error}

Strict Rules

• Do NOT pollute main context with full tool catalogs — always delegate discovery to a subagent
• Do NOT call MCP tools without first matching them to the task
• Do NOT modify .mcp.json without explicit user confirmation
• Do NOT bypass the per-server config — load references/configuration.md for the server's quirks
• Do NOT hardcode server names or tool names — read from the cached capability map

End every response with the subagent status block:

**Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
**Summary:** [1-2 sentence summary]
**Files modified:** [comma-separated list]
**Concerns/Blockers:** [if applicable]