Code Execution

The code_execution tool enables orchestrating multiple upstream MCP tools in a single request using sandboxed JavaScript (ES2020+) or TypeScript.

Overview

Code execution allows AI agents to:

Chain multiple tool calls together
Process and transform tool outputs
Implement complex logic and conditionals
Reduce round-trip latency

Configuration

Enable code execution in your config:

json

{
  "enable_code_execution": true,
  "code_execution_timeout_ms": 120000,
  "code_execution_max_tool_calls": 0,
  "code_execution_pool_size": 10
}

Option	Type	Default	Description
`enable_code_execution`	boolean	`false`	Enable the code execution tool
`code_execution_timeout_ms`	integer	`120000`	Execution timeout (2 minutes)
`code_execution_max_tool_calls`	integer	`0`	Max tool calls (0 = unlimited)
`code_execution_pool_size`	integer	`10`	Number of VM instances to pool

CLI Usage

Basic Execution

bash

mcpproxy code exec --code="({ result: input.value * 2 })" --input='{"value": 21}'

TypeScript Execution

bash

mcpproxy code exec --language typescript --code="const x: number = 42; ({ result: x })"

Tool Orchestration

bash

mcpproxy code exec --code="call_tool('github', 'get_user', {username: input.user})" --input='{"user":"octocat"}'

API

Input Schema

json

{
  "code": "string (required) - JavaScript or TypeScript code to execute",
  "language": "string (optional) - 'javascript' (default) or 'typescript'",
  "input": "object (optional) - Input data available as 'input' variable"
}

Built-in Functions

call_tool(server, tool, args)

Execute a tool on an upstream server:

javascript

var result = call_tool('github', 'create_issue', {
  repo: 'owner/repo',
  title: 'Bug report',
  body: 'Description'
});

log(message)

Log a message (visible in tool response):

javascript

log('Processing started');

Return Value

The last expression in the code is returned as the tool result:

javascript

// Return an object
({
  success: true,
  data: result
})

Examples

Simple Calculation

javascript

// input: { "a": 5, "b": 3 }
({ sum: input.a + input.b })

Tool Chaining

javascript

// Get user info then create an issue
var user = call_tool('github', 'get_user', { username: input.username });
var issue = call_tool('github', 'create_issue', {
  repo: input.repo,
  title: 'Issue from ' + user.name,
  body: 'Created by code execution'
});
({ user: user, issue: issue })

Conditional Logic

javascript

var files = call_tool('filesystem', 'list_directory', { path: input.path });

if (files.length > 100) {
  ({ status: 'too_many_files', count: files.length });
} else {
  var results = [];
  for (var i = 0; i < files.length; i++) {
    if (files[i].endsWith('.md')) {
      results.push(files[i]);
    }
  }
  ({ markdown_files: results });
}

Error Handling

javascript

try {
  var result = call_tool('api', 'fetch_data', { url: input.url });
  ({ success: true, data: result });
} catch (e) {
  ({ success: false, error: e.message });
}

Security

Sandbox Environment

Code runs in isolated JavaScript VM (goja)
No access to file system
No access to network (except via call_tool)
No access to process environment
Memory limits enforced

Tool Call Security

Tools inherit quarantine status
Rate limiting applied
Response size limits enforced

Troubleshooting

Timeout Errors

Increase the timeout or optimize your code:

json

{
  "code_execution_timeout_ms": 300000
}

Syntax Errors

Modern JavaScript syntax (ES2020+) is fully supported, including arrow functions, const/let, template literals, destructuring, optional chaining, and nullish coalescing:

javascript

// All of these work
const result = () => call_tool('server', 'tool');
const name = user?.profile?.name ?? 'unknown';
const msg = `Hello, ${name}!`;
const { data, error } = response;

Tool Not Found

Verify the server and tool names:

bash

mcpproxy tools list --server=server-name

TypeScript Support

Set language: "typescript" to write code with type annotations. TypeScript types are automatically stripped before execution using esbuild, with near-zero transpilation overhead (<5ms).

Supported Features

Type annotations: const x: number = 42
Interfaces: interface User { name: string; age: number; }
Type aliases: type StringOrNumber = string | number
Generics: function identity<T>(arg: T): T { return arg; }
Enums: enum Direction { Up = "UP", Down = "DOWN" }
Namespaces and type assertions

Example

bash

mcpproxy code exec --language typescript \
  --code="interface User { name: string; }
const user: User = { name: input.username };
({ greeting: 'Hello ' + user.name })" \
  --input='{"username": "Alice"}'

Important Notes

TypeScript support uses type-stripping only (no type checking or semantic validation)
Valid JavaScript is also valid TypeScript
Transpilation errors return the TRANSPILE_ERROR error code with line/column information
See docs/code_execution/overview.md in the repository for comprehensive TypeScript documentation

Best Practices

Keep code simple: Complex logic is harder to debug
Handle errors: Use try/catch for tool calls
Minimize tool calls: Batch operations when possible
Use logging: Add log() calls for debugging
Test locally: Use CLI to test before integrating