mcp-executor

Code Executor Skill for Claude Code

A comprehensive Claude Code skill that enables efficient multi-tool MCP workflows by launching subagents that write and execute code, reducing token overhead by up to 98%.

Overview

This skill teaches Claude Code how to handle complex MCP workflows efficiently using a subagent architecture. Instead of loading all MCP tool schemas into the main context (causing token bloat), Claude Code launches a subagent that writes TypeScript or Python code to compose multiple MCP tool calls.

Key Benefits

• 98% Token Reduction: Main context has NO MCP servers → no token bloat (1.6k vs 141k tokens)
• Multi-Tool Composition: Combine multiple MCP operations in single code execution
• Complex Logic: Loops, conditionals, data transformations, retry logic
• Parallel Execution: Fetch from multiple sources simultaneously
• Cached Patterns: 12 proven script examples (6 TypeScript + 6 Python)
• Progressive Disclosure: Load MCP tools only in subagent context

Architecture

Main Claude Code (NO MCP servers configured)
    ↓
    Recognizes multi-tool MCP workflow
    ↓
    Launches subagent via Task tool
    ↓
Subagent (HAS MCP servers configured)
    ↓
    Writes TypeScript/Python code
    ↓
    Executes via Bash (deno run / python)
    ↓
    Code imports local MCP client library
    ↓
    MCP client calls tools via MCP protocol
    ↓
    Returns results to main context

Why this works:

• Main context stays clean (no MCP schemas loaded)
• Subagent context is isolated and disposable
• Code execution allows complex multi-tool composition
• Results summarized and returned to main

Prerequisites

Required

1. Claude Code (terminal or web version)

   • Get it: https://docs.claude.com/en/docs/claude-code

2. Deno (for TypeScript execution)

   curl -fsSL https://deno.land/install.sh | sh
   

3. Python 3.8+ (for Python execution)

   python3 --version  # Should be 3.8 or higher
   

4. MCP Servers you want to use

   • Filesystem: @modelcontextprotocol/server-filesystem
   • PostgreSQL: mcp-server-postgres
   • SQLite: mcp-server-sqlite
   • GitHub: mcp-server-github
   • Or your custom MCP servers

NOT Required

• ❌ code-executor-MCP server (we implement MCP client locally)
• ❌ MCP servers in main Claude Code configuration (keeps context clean)

Installation

Step 1: Install the Skill

# Clone this repository
git clone https://github.com/mcfearsome/cc-mcp-executor-skill.git

# Install for main Claude Code instance (global)
cp -r cc-mcp-executor-skill/code-executor ~/.claude/skills/

# OR install for specific project (local)
mkdir -p .claude/skills
cp -r cc-mcp-executor-skill/code-executor .claude/skills/

Step 2: Configure Subagent MCP Servers

Create ~/.claude/subagent-mcp.json (or project-specific .claude/subagent-mcp.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp", "/home/user/projects"]
    },
    "postgres": {
      "command": "mcp-server-postgres",
      "args": ["--connection", "postgresql://localhost/mydb"]
    },
    "github": {
      "command": "mcp-server-github",
      "args": ["--token-file", "/home/user/.github-token"]
    }
  }
}

Step 3: Understand MCP Client Configuration

The MCP client library reads configuration from ~/.mcp.json or MCP_CONFIG_PATH env var.

CRITICAL: Do NOT symlink or globally export MCP_CONFIG_PATH

Why? If you symlink ~/.claude/subagent-mcp.json to ~/.mcp.json, or globally export MCP_CONFIG_PATH, then main Claude Code will load all MCP servers, defeating the entire purpose (98% token reduction).

Correct approach:

The subagent sets MCP_CONFIG_PATH temporarily in the Bash execution command:

MCP_CONFIG_PATH=~/.claude/subagent-mcp.json deno run --allow-read --allow-run --allow-env script.ts

This way:

• ✅ Main Claude Code has NO MCP servers loaded (keeps context clean)
• ✅ Subagent execution sets MCP_CONFIG_PATH temporarily
• ✅ MCP client reads from subagent config only during code execution
• ✅ Token overhead isolated to subagent context

No action needed in this step - the subagent handles setting MCP_CONFIG_PATH automatically when executing code.

Step 4: Verify Installation

# Check skill is installed
ls -la ~/.claude/skills/code-executor/

# You should see:
# - SKILL.md (main skill file)
# - SUBAGENT_SETUP.md (configuration guide)
# - lib/ (MCP client libraries)
# - scripts/ (cached patterns)
# - templates/ (starting points)

Quick Start

Example 1: Simple File Processing

User Request:

"Read all JSON files in /tmp/data and count total records"

Claude Code (main): Recognizes multi-tool workflow → launches subagent