README.md
MCP server that lets AI agents execute code instead of calling tools directly.
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:
- Tool definition overload - Loading all tool definitions floods context
- 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.
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 |
| Context Efficiency | Filtering happens in sandbox, model sees results only |
| Variable Persistence | Store results as $invoices, $customers for later use |
| FTS5 Search | Auto-index large outputs, search with intent parameter |
| Batch Operations | mcx_batch for multiple operations in one call |
| File Processing | mcx_file to process local files with $file injection |
| URL Fetching | mcx_fetch with HTML-to-markdown conversion |
| 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 variable injection |
mcx_fetch |
Fetch URLs with HTML-to-markdown and auto-indexing |
mcx_list |
List available adapters and skills |
mcx_stats |
Session statistics (indexed content, variables) |
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, 1
Tools (8)
mcx_executeExecute code with adapter access, auto-stores as $resultmcx_search3 modes: spec exploration, FTS5 search, adapter/method searchmcx_batchMultiple executions/searches in one callmcx_fileProcess local files with $file variable injectionmcx_fetchFetch URLs with HTML-to-markdown and auto-indexingmcx_listList available adapters and skillsmcx_statsSession statistics (indexed content, variables)mcx_run_skillRun a registered skillEnvironment Variables
API_CREDENTIALSrequiredAPI keys and credentials stored in ~/.mcx/.envConfiguration
claude_desktop_config.json
{"mcpServers": {"mcx": {"command": "mcx", "args": ["serve"]}}}Try it
→Use mcx_execute to fetch the last 50 invoices and return only the total sum of amounts.
→Search for the Supabase adapter methods using mcx_search.
→Fetch the content of https://example.com and convert it to markdown using mcx_fetch.
→Process the local file data.json using mcx_file to extract specific fields.