MCP Code Execution

Transform any MCP server into executable, type-safe TypeScript tools using progressive loading pattern. Achieve 98% token savings by loading only what you need.

[!TIP]
Inspired by Anthropic's engineering blog post on Code Execution with MCP.

The Problem

Traditional MCP integration loads ALL tools from a server (~30,000 tokens), even when you only need one or two. This wastes context window space and slows down AI agents.

The Solution

Progressive loading generates one TypeScript file per tool (~500-1,500 tokens each). AI agents discover and load only what they need via simple ls and cat commands.

Result: 98% token savings + autonomous execution + type safety

Installation

From crates.io (recommended)

cargo install mcp-execution-cli

Pre-built binaries

Download from GitHub Releases:

# macOS (Apple Silicon)
curl -L https://github.com/bug-ops/mcp-execution/releases/latest/download/mcp-execution-cli-macos-arm64.tar.gz | tar xz

# macOS (Intel)
curl -L https://github.com/bug-ops/mcp-execution/releases/latest/download/mcp-execution-cli-macos-amd64.tar.gz | tar xz

# Linux (x86_64)
curl -L https://github.com/bug-ops/mcp-execution/releases/latest/download/mcp-execution-cli-linux-amd64.tar.gz | tar xz

# Linux (ARM64)
curl -L https://github.com/bug-ops/mcp-execution/releases/latest/download/mcp-execution-cli-linux-arm64.tar.gz | tar xz

# Windows (x86_64)
# Download mcp-execution-cli-windows-amd64.zip from releases page

From source

git clone https://github.com/bug-ops/mcp-execution
cd mcp-execution
cargo install --path crates/mcp-cli

As a library

Add individual crates to your project:

cargo add mcp-execution-core          # Foundation types
cargo add mcp-execution-introspector  # MCP server analysis
cargo add mcp-execution-codegen       # TypeScript generation
cargo add mcp-execution-files         # Virtual filesystem
cargo add mcp-execution-skill         # SKILL.md generation

Or add to Cargo.toml:

[dependencies]
mcp-execution-core = "0.6"
mcp-execution-introspector = "0.6"
mcp-execution-codegen = "0.6"

[!IMPORTANT]
Requires Rust 1.89 or later for building from source.

Usage

Generate TypeScript Tools

# 1. Configure MCP server in ~/.claude/mcp.json
# 2. Generate tools
mcp-execution-cli generate --from-config github

# Output: ~/.claude/servers/github/
#   - createIssue.ts
#   - updateIssue.ts
#   - ... (one file per tool)

Progressive Loading

# List available tools
ls ~/.claude/servers/github/

# Load only what you need (98% token savings!)
cat ~/.claude/servers/github/createIssue.ts

# Execute autonomously
node ~/.claude/servers/github/createIssue.ts --repo="owner/repo" --title="Bug"

[!NOTE]
Each tool file is self-contained with full TypeScript interfaces and JSDoc documentation.

Key Features

Feature	Description
98% Token Savings	Load 1 tool (~500 tokens) vs all tools (~30,000 tokens)
Autonomous Execution	Generated files run directly via Node.js CLI
Type-Safe	Full TypeScript interfaces from MCP JSON schemas
Lightning Fast	526x faster than target (0.19ms for 10 tools)
100% MCP Compatible	Works with all MCP servers via rmcp SDK
Thoroughly Tested	556 tests with 100% pass rate

Workspace Crates

Crate	Description
mcp-execution-core	Foundation types, traits, and error handling
mcp-execution-introspector	MCP server analysis using rmcp SDK
mcp-execution-codegen	TypeScript code generation with progressive loading
mcp-execution-files	Virtual filesystem for code organization
mcp-execution-skill	SKILL.md generation for Claude Code
mcp-execution-server	MCP server for progressive loading generation
mcp-execution-cli	Command-line interface

Dependency Graph:

mcp-execution-cli → {mcp-execution-codegen, mcp-execution-introspector, mcp-execution-files, mcp-execution-core, mcp-execution-skill}
mcp-execution-server → {mcp-execution-codegen, mcp-execution-introspector, mcp-execution-files, mcp-execution-core, mcp-execution-skill}
mcp-execution-codegen → {mcp-execution-introspector, mcp-execution-core}
mcp-execution-files → mcp-execution-codegen
mcp-execution-introspector → {rmcp, mcp-execution-core}
mcp-execution-skill → mcp-execution-core

CLI Commands

See mcp-cli README for full reference.

# Generate TypeScript tools from config (recommended)
mcp-execution-cli generate --from-config github

# Introspect MCP server from config (v0.6.3+)
mcp-execution-cli introspect --from-config github

# Introspect with detailed schemas
mcp-execution-cli introspect --from-config github --detailed

# Manual configuration (alternative)
mcp-execution-cli introspect docker --arg=run --arg=-i --env=TOKEN=xxx

# Shell completions
mcp-execution-cli completions bash

[!TIP]
Use --from-config to load server settings from ~/.claude/mcp.json instead of manual arguments.

Performance

Metric	Target	Achieved
10 tools generation	<100ms	0.19ms (526x faster)
50 tools generation	<20ms	0.97ms (20.6x faster)
VFS export	<10ms	1.2ms (8.3x faster)
Memory (1000 tools)	<256MB	~2MB

Documentation

Progressive Loading Tutorial - Complete guide
Claude Code Integration - Skill setup
Architecture Decisions - ADRs explaining design choices

Development

cargo build --workspace        # Build
cargo nextest run --workspace  # Test
cargo clippy --workspace       # Lint
cargo +nightly fmt --workspace # Format

[!NOTE]
All development follows Microsoft Rust Guidelines.

MSRV Policy

Minimum Supported Rust Version: 1.89

MSRV increases are considered minor version bumps.

License

Licensed under either of Apache License 2.0 or MIT license at your option.