codemode
Two MCP tools that replace hundreds. Give an AI agent your OpenAPI spec and a request handler — it discovers and calls your entire API by writing JavaScript in a sandboxed runtime.
Instead of defining individual MCP tools for every API endpoint (list-pods, create-product, get-logs, ...), CodeMode exposes just two tools:
search— the agent writes JS to filter your OpenAPI spec and discover endpointsexecute— the agent writes JS to call your API via an injected client
This is the same pattern Cloudflare uses to expose 2,500+ API endpoints through just two MCP tools, reducing context window usage by 99.9%.
Try It
Requires mise for tooling (Node.js, pnpm, Task):
git clone https://github.com/akua-dev/codemode.git
cd codemode
mise install # installs Node 24, pnpm 10, Task
task install # installs dependencies
task example # runs the Petstore demo
Fetches the real Petstore OpenAPI spec from the web, then runs search + execute against a local Hono mock — no API keys needed.
Install
pnpm add @robinbraemer/codemode
# Install a sandbox runtime (at least one):
pnpm add @robinbraemer/llrt # Native LLRT — default candidate
pnpm add isolated-vm # V8 isolates — data-only Node.js fallback
If both are installed, the auto-selector (createExecutor) picks native LLRT first, then isolated-vm on Node for data-only execution. Request-capable execution requires LLRT. QuickJSExecutor is still exported for explicit advanced use, but it is not selected automatically because its host-callback bridge cannot enforce all byte limits before values cross into host JavaScript.
Quick Start
import { CodeMode } from '@robinbraemer/codemode';
import { Hono } from 'hono';
const app = new Hono();
app.get('/v1/clusters', (c) => c.json([{ id: '1', name: 'prod' }]));
app.post('/v1/clusters', async (c) => {
const body = await c.req.json();
return c.json({ id: '2', ...body }, 201);
});
const codemode = new CodeMode({
spec: myOpenAPISpec, // OpenAPI 3.x spec, or async getter
request: app.request.bind(app), // in-process, no network hop
});
// The agent searches the spec to discover endpoints...
const search = await codemode.callTool('search', {
code: `async () => {
const results = [];
for (const [path, methods] of Object.entries(spec.paths)) {
for (const [method, op] of Object.entries(methods)) {
if (op.tags?.some(t => t.toLowerCase() === 'clusters')) {
results.push({ method: method.toUpperCase(), path, summary: op.summary });
}
}
}
return results;
}`
});
// ...then executes API calls
const result = await codemode.callTool('execute', {
code: `async () => {
const res = await api.request({ method: "GET", path: "/v1/clusters" });
return res.body;
}`
});
MCP Server Integration
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CodeMode } from '@robinbraemer/codemode';
import { registerTools } from '@robinbraemer/codemode/mcp';
const codemode = new CodeMode({
spec: () => fetchOpenAPISpec(),
request: app.request.bind(app),
});
const server = new McpServer({ name: 'my-api', version: '1.0.0' });
registerTools(codemode, server);
const transport = new StdioServerTransport();
await server.connect(transport);
How It Works
AI Agent
│ writes JavaScript code
▼
CodeMode MCP Server
│
├─ search(code) → runs JS with preprocessed OpenAPI spec
│ → ref-resolved paths view with only essential fields kept
│ → agent discovers endpoints, schemas, parameters
│
└─ execute(code) → runs JS with injected request client
→ api.request() calls your handler in-process
→ no network hop, auth handled automatically
All code runs in a fresh sandbox runtime. The sandbox has zero I/O by default — no require, no process, no fetch, no filesystem. Request-capable execution uses injected host callbacks (spec for search, {namespace}.request() for execute) and is supported by LLRT.
Each tool call gets a fresh sandbox with no state carried over between calls.
API
new CodeMode(options)
Successful spec preprocessing is cached. Concurrent searches share an in-flight async spec provider, while a failed preparation is retried by a later search.
Data-only input first has a 100,000-node structural inspection limit. Built-in
executors additionally reject cycles, bigint, and custom toJSON hooks, then
preflight the fully expanded transport shape before marshalling it into a
sandbox. Shared aliases count once per transport occurrence, with limits of
500,000 expanded occurrences and 10 MiB of encoded input. Custom executors still
receive the alias-preserving structured clone and remain responsible for their
own transport limits.
SandboxOptions
Methods
codemode.tools(): ToolDefinition[]
Returns MCP-compatible tool definitions for search and execute.
codemode.callTool(name, { code }): Promise<ToolCallResult>
Route a tool call. Returns { content: [{ type: "text", text }], isError? }.
codemode.search(code): Promise<ToolCallResult>
Run search code directly (shorthand for callTool('search', { code })).
codemode.execute(code): Promise<ToolCallResult>
Run execute code directly (shorthand for callTool('execute', { code })).
codemode.setToolNames(search, execute): this
Override default tool names. Useful when running multiple CodeMode instances.
codemode.dispose(): void
Clean up sandbox resources.
Sandbox API
Inside search
The spec global is the preprocessed OpenAPI paths view; resolvable $ref pointers are expanded inline:
// Find endpoints by tag
async () => {
const results = [];
for (const [path, methods] of Object.entries(spec.paths)) {
for (const [method, op] of Object.entries(methods)) {
if (op.tags?.some(t => t.toLowerCase() === 'clusters')) {
results.push({ method: method.toUpperCase(), path, summary: op.summary });
}
}
}
return results;
}
// Get endpoint with requestBody schema (resolvable refs are expanded)
async () => {
const op = spec.paths['/v1/products']?.post;
return { summary: op?.summary, requestBody: op?.requestBody };
}
// Spec shape
async () => ({
endpoints: Object.keys(spec.paths).length,
})
Inside execute
The {namespace}.request() function makes API calls through the host handler:
// GET with query params
async () => {
const res = await api.request({
method: "GET",
path: "/v1/clusters",
query: { limit: 10 },
});
return res.body;
}
// POST with body
async () => {
const res = await api.request({
method: "POST",
path: "/v1/products",
body: { name: "Redis", chart: "bitnami/redis" },
});
return { status: res.status, body: res.body };
}
// Chain calls
async () => {
const list = await api.request({ method: "GET", path: "/v1/clusters" });
const details = await Promise.all(
list.body.map(c =>
api.request({ method: "GET", path: `/v1/clusters/${c.id}` })
)
);
return details.map(d => d.body);
}
Request options:
Response: { status: number, headers: Record<string, string>, body: unknown }
Spec Preprocessing
CodeMode automatically preprocesses your OpenAPI spec before passing it to the search sandbox:
$refresolution — resolvable$refpointers are expanded inline; circular refs become{ $circular: ref }, and refs beyondmaxRefDepthbecome{ $circular: ref, $reason: "max depth exceeded" }- Field extraction — only essential fields kept per operation:
summary,description,tags,parameters,requestBody,responses - Output shape — only
{ paths }is passed to search;info,servers, andcomponentsare omitted because operation fields and resolved references are represented in the paths view
You can also use the preprocessing utilities directly:
import { resolveRefs, processSpec, extractTags } from '@robinbraemer/codemode';
const processed = processSpec(rawSpec);
const tags = extractTags(rawSpec);
Executors
CodeMode ships three executor backends. LlrtNativeExecutor is the default and the only request-capable backend. IsolatedVMExecutor is the Node.js data-only fallback, and QuickJSExecutor is an explicit data-only compatibility backend.
Use createExecutor() for automatic selection, or pass an executor instance explicitly:
import { CodeMode, createExecutor, IsolatedVMExecutor, LlrtNativeExecutor } from '@robinbraemer/codemode';
// Automatic — picks native LLRT first, then data-only isolated-vm on Node
const codemode = new CodeMode({
spec,
request: handler,
executor: await createExecutor({ memoryMB: 128, timeoutMs: 60_000 }),
});
// Or explicit
const codemode = new CodeMode({
spec,
request: handler,
executor: new IsolatedVMExecutor({
memoryMB: 128,
timeoutMs: 60_000, // CPU time limit
wallTimeMs: 120_000, // total elapsed time limit
}),
});
QuickJSExecutor caveats
- Not a production backend and not auto-selected. Use this only by constructing
new QuickJSExecutor(...)explicitly. Production request-capable callers should useLlrtNativeExecutor. - Host callbacks are disabled. QuickJS cannot enforce host-call byte limits before guest values are dumped into host JavaScript, and sequential host awaits still hit upstream release-asyncify crashes.
QuickJSExecutornow fails closed when function globals are provided. - Return-value semantics differ from
isolated-vm. Final values cross via aJSON.stringifyenvelope.Date,Map,Set,BigIntare converted to strings/objects, not preserved as instances.isolated-vmuses structured clone and preserves them. Stick to plain JSON-safe shapes in sandboxed code that targets both backends. - CPU timeout is wall-clock-based.
isolated-vmuses true CPU time; QuickJS uses elapsed time.
Custom Executor
Implement the Executor interface to use your own sandbox:
CodeMode passes a fresh structured clone of the processed spec to each search() call, so mutations made by a custom executor cannot change later searches.
CodeMode calls executeData() for search() and executeWithCapabilities() for execute(). Implement the latter when the custom runtime needs to expose the request capability; the legacy execute() method remains available for direct executor use.
import {
CodeMode,
emptyExecuteStats,
type CapabilityManifest,
type ExecuteResult,
type Executor,
} from '@robinbraemer/codemode';
class MyExecutor implements Executor {
async executeData(_code: string, _input: Record<string, unknown>): Promise<ExecuteResult> {
// Run data-only code in the sandbox.
return { result: undefined, stats: emptyExecuteStats() };
}
async executeWithCapabilities(
_code: string,
_input: Record<string, unknown>,
_capabilities: CapabilityManifest,
): Promise<ExecuteResult> {
// Run code with declared capabilities, such as `{namespace}.request()`.
return { result: undefined, stats: emptyExecuteStats() };
}
async execute(_code: string, _globals: Record<string, unknown>): Promise<ExecuteResult> {
// Legacy direct-executor entrypoint.
return { result: undefined, stats: emptyExecuteStats() };
}
dispose() { /* clean up */ }
}
const codemode = new CodeMode({
spec,
request: handler,
executor: new MyExecutor(),
});
Token Efficiency
License
MIT
