Code Mode
Replace the flat tool list with two tools — search and execute — that let the model write JavaScript against a sandboxed Home Assistant SDK.
Code Mode is the pattern from Cloudflare’s Code Mode MCP post: instead of advertising every operation as its own tool, the server exposes two tools, search and execute. The model writes a short JavaScript program, the server runs it in a sandbox, and only the result comes back. The full tool catalog never enters the model’s context.
Enable it
Set CODE_MODE in your environment or .env:
| Value | Effect |
|---|---|
off (default) | Classic tools only. Code Mode is not exposed. |
only | Expose just search + execute. Best context savings. |
both | Expose the classic tools and search + execute while you migrate. |
CODE_MODE=only
true, 1, yes, on, and code are accepted as aliases for only; all and add are accepted for both. Unknown values fall back to off, so a typo cannot take the server down.
The two tools
Both tools take one argument:
{
"code": "async () => { /* JavaScript */ }"
}
The code must be an async arrow function. It receives no arguments; it uses globals supplied by the server.
search
search is offline. It exposes spec, a JSON object describing the server:
spec.tools— every classic tool withname,description,inputSchema,annotations, and optionaloutputSchema.spec.hass— signatures for theexecuteSDK.spec.toolsApi— thetools.list/tools.callAPI.spec.helpers—sleepandconsole.spec.notes— short usage notes.
Example — find every light-related tool without loading the catalog:
async () => {
return spec.tools
.filter((tool) => /light/i.test(tool.name + " " + tool.description))
.map(({ name, description }) => ({ name, description }));
};
The result is whatever your function returns. The full spec stays on the server.
execute
execute runs against Home Assistant in a sandboxed QuickJS VM. Available globals:
| Global | Description |
|---|---|
hass.getStates() | Every entity state. |
hass.getState(entity_id) | One entity by ID. |
hass.callService(domain, service, data) | Call any Home Assistant service. |
hass.request({ method, path, body }) | Raw REST under /api/; the host is pinned to HASS_HOST. |
hass.getServices() | GET /api/services. |
hass.getConfig() | GET /api/config. |
hass.getHistory({ entity_id, start_time?, end_time? }) | State history. |
tools.list() | Names and descriptions of the classic tools. |
tools.call(name, args) | Invoke any classic tool, with Zod validation. JSON-string results are parsed. |
sleep(ms) | Wait; capped at 10 seconds and by the execution deadline. |
console.log(...) | Write to the server log. Output is not returned to the model. |
Example — find lights that are on and return only their names:
async () => {
const states = await hass.getStates();
return states
.filter((state) => state.entity_id.startsWith("light.") && state.state === "on")
.map((state) => state.entity_id);
};
Example — compose several calls in one execution:
async () => {
const lights = await tools.call("lights", { action: "list" });
const result = await hass.callService("light", "turn_on", {
entity_id: "light.kitchen",
brightness: 128,
});
return { lights, result };
};
Why two tools?
The classic server advertises 50+ tools. Every one of those descriptions and JSON schemas is sent to the model on every turn. In only mode the manifest is search + execute, so the fixed cost is a few hundred tokens no matter how many classic tools exist. The model discovers the rest progressively through search, or just calls tools.call when it already knows the name.
Security model
Generated code runs in a QuickJS WebAssembly VM, not in the Node/Bun process. The sandbox has:
- no filesystem access,
- no environment variables (so no
HASS_TOKEN), - no
require/import, - no
fetch,WebSocket, or timers beyondsleep, - no host object references: the only host capability is a JSON-in/JSON-out bridge.
hass.request is restricted to the configured HASS_HOST origin and to paths under /api/. Paths that traverse (..) or point at another host are rejected, and outbound redirects are rejected (redirect: "error"), so a redirect cannot smuggle the request — or the token — to another host. tools.call cannot invoke search or execute recursively.
Each execution gets its own QuickJS WebAssembly module. That keeps concurrent MCP requests isolated and lets an interrupted or timed-out execution be discarded safely. Executions are capped at CODE_MODE_MAX_HOST_CALLS (default 100) host-bridge calls per run, and at most CODE_MODE_MAX_CONCURRENT (default 4) sandboxes run at a time; executions beyond the cap wait for a free slot before their wall-clock deadline is set.
Limits and tuning
| Variable | Default | Purpose |
|---|---|---|
CODE_MODE | off | off, only, or both. |
CODE_MODE_TIMEOUT_MS | 30000 | Wall-clock budget for one call. |
CODE_MODE_MAX_OUTPUT_BYTES | 262144 | Maximum JSON result returned to the model, measured in UTF-8 bytes; larger results are rejected with an error, not truncated. |
CODE_MODE_MAX_HOST_CALLS | 100 | Maximum host bridge calls per execution. |
CODE_MODE_MAX_CONCURRENT | 4 | Maximum sandboxes running concurrently. |
CODE_MODE_MEMORY_LIMIT_BYTES | 67108864 | QuickJS heap limit per execution. |
CODE_MODE_MAX_STACK_BYTES | 1048576 | QuickJS stack limit per execution. |
CODE_MODE_ALLOW_TOOL_CALLS | true | Allow tools.call from sandboxed code. |
CODE_MODE_ALLOW_RAW_HTTP | true | Allow hass.request from sandboxed code. |
Timeouts and oversized results are reported as tool errors. console.log output is logged at debug level on the server, so set LOG_LEVEL=debug while developing a script. Values above the built-in ceilings are clamped (CODE_MODE_TIMEOUT_MS ≤ 300000, CODE_MODE_MAX_OUTPUT_BYTES ≤ 4194304, CODE_MODE_MEMORY_LIMIT_BYTES ≤ 536870912, CODE_MODE_MAX_STACK_BYTES ≤ 16777216, CODE_MODE_MAX_HOST_CALLS ≤ 10000, CODE_MODE_MAX_CONCURRENT ≤ 16); unrecognized boolean values are treated as true.
When not to use it
Code Mode is a poor fit if your client cannot display or debug JavaScript, or if you rely on MCP clients that discover capabilities only through tools/list. In those cases leave CODE_MODE=off and keep the classic tools.
Next
- Configuration > Tools — annotations and per-tool toggles.
- Architecture > Tool System — how classic tools are defined and registered.