Code-mode architecture

The problem it solves

By default, klaridian makes one MCP tool per OpenAPI operation. That's fine for small specs. On a large one—dozens or hundreds of operations—it produces a bloated tool list that costs agents context and makes them more likely to pick the wrong tool.

What code-mode generates instead

npx klaridian generate --spec ./api.yaml --out ./my-server \
  --architecture code-mode \
  --base-url https://api.example.com

Instead of one tool per operation, you get exactly two tools:

• search_docs—look up a function's signature and purpose before writing code against it.
• execute_code—run TypeScript against a typed, validated client. One function per operation, generated from your spec.

Why a sandboxed subprocess

Code passed to execute_code runs in an isolated Deno subprocess, not inside the server's own process. The sandbox only allows:

• Network access to the target API's host—nothing else

• Reading the generated client's own files—nothing else

• No file writes, no subprocess spawning, no arbitrary file reads

• No module downloads while running (Deno's default import hosts are blocked too)

These boundaries are tested directly, not just declared: a cross-host request is blocked, a file write attempt is blocked, reading outside the client's directory is blocked, and a remote import is blocked.

Each script is also limited in time and memory, so one bad script can't hang or exhaust the server: 30 seconds and a 256 MB heap by default. Set KLARIDIAN_SANDBOX_TIMEOUT (seconds) and KLARIDIAN_SANDBOX_MAX_HEAP_MB on the server to change them.

Python servers

Code-mode works with --language python too. The code the model writes is still TypeScript, run by the same Deno sandbox, because the model writes it, not you, and Python has no sandbox that can limit network access to one host the way Deno does.

You don't install Deno yourself: it comes from the official deno package on PyPI listed in requirements.txt.

npx klaridian generate --spec ./api.yaml --out ./my-server \
  --language python --architecture code-mode \
  --base-url https://api.example.com
cd my-server
python -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
python sandbox_runner.py --install   # once: installs the typed client's dependency
python server.py

sandbox_runner.py shows the exact Deno permissions.

Why this design

Independent benchmarks compared three approaches for letting an agent call a large API: a typed client + sandboxed execution (what klaridian does), a "dynamic" set of generic lookup/invoke tools, and Cloudflare's isolate-based code mode. The typed-client approach won clearly—the other two sometimes gave wrong answers with no sign anything was wrong.

Things to know

• A TypeScript code-mode server needs Deno installed where it runs. A Python one gets it from pip. klaridian deploy --target docker includes it in the image for both.
• --base-url must be an absolute URL. The sandbox's network permission is fixed at generation time, so there's no way to fall back if it's missing.
• Plugins work with code mode in both languages. --plugin otel records a span for each execute_code call and, under it, one child span for each API call the script made. The analytics plugins (posthog, amplitude, mixpanel) add the operations the script called to the event. Arguments and response bodies are never recorded.
• execute_code's annotations describe every operation it can reach. If any exposed operation deletes or replaces data, execute_code is marked destructive, so a client that asks for confirmation on destructive tools will ask for every script. To get a read-only execute_code, generate with only read operations (for example --include-methods GET).
• You pick one architecture per server. tools and code-mode don't mix in a single generation.