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%.
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 demoFetches the real Petstore OpenAPI spec from the web, then runs search + execute against a local Hono mock — no API keys needed.
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 fallbackIf 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.
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;
}`
});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);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.
| Option | Type | Default | Description |
|---|---|---|---|
spec |
OpenAPISpec | () => OpenAPISpec | Promise<OpenAPISpec> |
required | OpenAPI 3.x spec or async getter |
request |
(input, init?) => Response |
required | Fetch-compatible handler (app.request.bind(app) for Hono) |
namespace |
string |
"api" |
Client name in sandbox (api.request(...)). Must be a valid JS identifier, not a reserved name. |
baseUrl |
string |
"http://localhost" |
Base URL for relative paths |
sandbox |
SandboxOptions |
see below | Sandbox resource limits |
executor |
Executor |
createExecutor() |
Custom sandbox executor |
maxResponseTokens |
number |
25000 |
Token limit for response truncation (0 to disable) |
maxRequests |
number |
50 |
Max requests per execute() call |
maxResponseBytes |
number |
10485760 |
Max response body size in bytes (10MB) |
allowedHeaders |
string[] |
undefined |
Header whitelist. When unset, a blocklist strips Authorization, Cookie, Host, X-Forwarded-*, Proxy-*. |
maxRefDepth |
number |
50 |
Max $ref resolution depth |
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.
| Option | Type | Default | Description |
|---|---|---|---|
memoryMB |
number |
64 |
Sandbox heap memory limit |
timeoutMs |
number |
30000 |
CPU timeout in ms (caps pure compute) |
wallTimeMs |
number |
60000 |
Wall-clock timeout in ms (caps total elapsed time including async I/O) |
Returns MCP-compatible tool definitions for search and execute.
Route a tool call. Returns { content: [{ type: "text", text }], isError? }.
Run search code directly (shorthand for callTool('search', { code })).
Run execute code directly (shorthand for callTool('execute', { code })).
Override default tool names. Useful when running multiple CodeMode instances.
Clean up sandbox resources.
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,
})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:
| Field | Type | Description |
|---|---|---|
method |
string |
HTTP method ("GET", "POST", etc.) |
path |
string |
API path ("/v1/clusters") |
query |
Record<string, string | number | boolean> |
Query parameters (optional) |
body |
unknown |
Request body, auto-serialized as JSON (optional) |
headers |
Record<string, string> |
Additional headers (optional) |
Response: { status: number, headers: Record<string, string>, body: unknown }
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);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
}),
});| Executor | Package | Performance | Portability | Production-ready |
|---|---|---|---|---|
LlrtNativeExecutor |
@robinbraemer/llrt |
Lightweight native LLRT | Node.js | ✅ default candidate |
IsolatedVMExecutor |
isolated-vm |
Native V8 speed | Node.js | |
QuickJSExecutor |
quickjs-emscripten |
Slower (interpreted WASM) | Node, Bun, CF Workers, browser |
- 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.
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(),
});| Approach | Context Tokens |
|---|---|
| Individual MCP tools (15-50+ tools) | ~15,000-50,000+ |
| Full OpenAPI spec in context | ~1,000,000+ |
| CodeMode (2 tools) | ~1,000 |
MIT