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 |

... View full README on GitHub