MCX (Modular Code Execution)

███╗   ███╗ ██████╗██╗  ██╗
████╗ ████║██╔════╝╚██╗██╔╝
██╔████╔██║██║      ╚███╔╝
██║╚██╔╝██║██║      ██╔██╗
██║ ╚═╝ ██║╚██████╗██╔╝ ██╗
╚═╝     ╚═╝ ╚═════╝╚═╝  ╚═╝

MCP server that lets AI agents execute code instead of calling tools directly.

Based on Anthropic's code execution article.

The Problem

Traditional MCP has two inefficiencies:

1. Tool definition overload - Loading all tool definitions floods context
2. Intermediate result bloat - Every API response passes through the model

The Solution

Instead of calling tools directly, the agent writes code that runs in a sandbox:

const invoices = await api.getInvoices({ limit: 100 });
return {
  count: invoices.length,
  total: sum(invoices, 'amount'),
  byStatus: count(invoices, 'status')
};
// Returns ~50 tokens instead of 50,000

Result: 98% token reduction by filtering data inside the execution environment.

Installation

# Install globally with bun
bun add -g @papicandela/mcx-cli

# Initialize global directory (~/.mcx/)
mcx init

Requires Bun: MCX uses Bun for runtime. Install Bun if you haven't already.

Quick Start

# 1. Initialize global MCX directory
mcx init

# 2. Generate adapters from API docs
mcx gen ./api-docs.md -n myapi

# 3. Add credentials to ~/.mcx/.env

# 4. Start server
mcx serve

Directory Structure

~/.mcx/
├── adapters/           # Your adapters
│   ├── supabase.ts     # Supabase Management API
│   ├── chrome-devtools.ts  # Chrome DevTools Protocol
│   └── myapi.ts        # Generated from OpenAPI
├── skills/             # Reusable skills
├── mcx.config.ts       # Auto-loads all adapters
├── .env                # API credentials
└── package.json        # Dependencies

# Runtime (created automatically)
~/.mcx/
├── logs/               # Server logs (mcx logs to view)
└── .cache/             # FTS5 search index

Claude Code Integration

Add to your Claude Code settings (~/.claude.json or project's .mcp.json):

{
  "mcpServers": {
    "mcx": {
      "command": "mcx",
      "args": ["serve"]
    }
  }
}

That's it! MCX automatically uses ~/.mcx/ for config and adapters.

Claude Code Hooks (Optional)

Redirect native tools to MCX alternatives for better performance:

~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Grep", "hooks": [{ "type": "command", "command": "bun ~/.claude/hooks/mcx-redirect.js" }] },
      { "matcher": "Glob", "hooks": [{ "type": "command", "command": "bun ~/.claude/hooks/mcx-redirect.js" }] },
      { "matcher": "Edit", "hooks": [{ "type": "command", "command": "bun ~/.claude/hooks/mcx-redirect.js" }] },
      { "matcher": "Write", "hooks": [{ "type": "command", "command": "bun ~/.claude/hooks/mcx-redirect.js" }] },
      { "matcher": "Read", "hooks": [{ "type": "command", "command": "bun ~/.claude/hooks/mcx-read-check.js" }] },
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "bun ~/.claude/hooks/mcx-bash-check.js" }] }
    ]
  }
}

Native Tool	MCX Alternative	Advantage
Glob	mcx_find	Frecency ranking, git status, proximity boost
Grep	mcx_grep	SIMD-accelerated, fuzzy search
Edit	mcx_edit	No "read first" requirement, CRLF normalization
Write	mcx_write	No "read first" requirement
Read (>50KB)	mcx_file({ storeAs })	File stays in sandbox, 99% token savings
Bash cat/grep/find	mcx_file/mcx_grep/mcx_find	Redirects shell commands to MCX

See Hooks Integration for hook scripts.

Key Features

Feature	Description
Lazy Loading	Adapters from ~/.mcx/adapters/ metadata-scanned at startup, fully loaded on first use
Domain Hints	Adapters grouped by domain (payments, database, email, etc.) for better discoverability
Silent Auto-Correction	executeSql auto-corrects to execute_sql (camelCase to snake_case)
Context Efficiency	Filtering happens in sandbox, model sees results only
Variable Persistence	Store results as $invoices, $customers for later use
Auto-Compress	Stale variables (>5min, >1KB) auto-compressed to save context
FTS5 Search	Auto-index large outputs, search with intent parameter
FFF Integration	Fast File Finder - SIMD-accelerated fuzzy search, content grep
Background Tasks	mcx_spawn for long-running operations, check with mcx_tasks
Batch Operations	mcx_batch for multiple operations in one call
File Processing	mcx_file to process local files with $file injection
Large File Handling	Files >50KB stay in sandbox via storeAs, query with helpers
File Editing	mcx_edit (string/line modes), mcx_write - no "read first" requirement
File Query Helpers	around(), lines(), block(), grep(), outline() for stored files
URL Fetching	mcx_fetch with HTML-to-markdown conversion (24h TTL cache)
Control Flow	Loops, conditionals, retries run as native code
Privacy	Intermediate data stays in sandbox
Security	Network isolation, path traversal protection, env injection prevention

MCP Tools

Tool	Description
mcx_execute	Execute code with adapter access, auto-stores as $result
mcx_search	3 modes: spec exploration, FTS5 search, adapter/method search
mcx_batch	Multiple executions/searches in one call (bypasses throttling)
mcx_file	Process local files with $file injection, or store-only mode with storeAs
mcx_edit	Edit files (string mode or line mode) - bypasses native Edit's read requirement
mcx_write	Create/overwrite files - bypasses native Write's read requirement
mcx_fetch	Fetch URLs with HTML-to-markdown and auto-indexing (24h cache)
mcx_find	Fast fuzzy file search with frecency + proximity ranking
mcx_grep	SIMD-accelerated content search across files
mcx_related	Find related files by imports/exports analysis
mcx_tree	Navigate large JSON results without loading full content
mcx_spawn	Run code in background, returns task ID immediately
mcx_tasks	List/check background tasks and their results
mcx_list	List available adapters and skills
mcx_stats	Session statistics (indexed content, variables, network)
mcx_doctor	Run diagnostics (Bun, SQLite, adapters, sandbox, FFF)
mcx_upgrade	Get self-upgrade command for latest version
mcx_run_skill	Run a registered skill

CLI Commands

Command	Description
mcx serve	Start MCP server (default)
mcx gen	Generate adapters from OpenAPI specs (with TUI)
mcx init	Initialize global ~/.mcx/ directory
mcx update	Update CLI and global installation
mcx list	List available adapters and skills
mcx run	Run a skill directly
mcx logs	View server logs

See CLI documentation for details.

Included Adapters

Adapter	Methods	Description
supabase	24	Supabase Management API (projects, tables, functions, secrets)
chrome-devtools	25	Chrome DevTools Protocol (screenshots, navigation, DOM)

Generate your own adapters from OpenAPI docs:

mcx gen ./api-docs.md -n myapi

Built-in Helpers

Functions available in the sandbox:

pick(data, ['id', 'name'])     // Extract fields
first(data, 5)                  // First N items
sum(data, 'amount')             // Sum numeric field
count(data, 'status')           // Count by field
table(data, 10)                 // Markdown table

// Async helpers
await poll(fn, { interval: 2000, maxIterations: 5 })  // Poll until done
await waitFor(fn, { timeout: 30000 })                  // Wait for condition

File Query Helpers

When using mcx_file({ path, storeAs }) to load files into sandbox:

// Load file without returning content to context (99% token savings)
mcx_file({ path: "src/large-file.ts", storeAs: "src" })

// Then query with helpers:
around($src, 150, 10)          // 10 lines around line 150
lines($src, 100, 120)          // Get lines 100-120 (1-indexed, inclusive)
block($src, 150)               // Extract code block by indentation
grep($src, "TODO", 3)          // Search with 3 lines context
outline($src)                  // Extract function/class signatures

Documentation

• CLI Commands - Detailed command reference
• Adapters - Creating and generating adapters
• Skills - Reusable operations
• Configuration - Config file reference
• Programmatic API - Using MCX in code
• Security - Sandbox security layers

Development

git clone https://github.com/schizoidcock/mcx
cd mcx
bun install
bun run build

License

MIT