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

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

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

• --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 (--plugin otel, --plugin posthog) aren't supported with code-mode yet—there's no per-operation hook to attach them to in the collapsed execute_code tool.
• You pick one architecture per server. tools and code-mode don't mix in a single generation.