Skip to main content

Integration

Code Mode offers three integration approaches: in the AI Web client, in an MCP Core server, or as a standalone package in any application. All three run the same sandbox in the browser or in Node.js, inside the host's own process, without an external execution service. This guide helps you choose the right approach for your architecture.

Integration Paths

Code Mode can run in AI Web, in an MCP Core server, or on its own.

Whichever approach you choose, generated code runs locally in an isolated sandbox, and your application keeps control over which tools the code can call.

Integration Paths at a Glance​

AI Web

Run Code Mode in the client so the assistant's programs can combine tools from every connected MCP server.

MCP Core server

Run Code Mode on the server for MCP clients that don't provide Code Mode themselves.

Standalone

Use the Code Mode package directly in any browser or Node.js application, with no other io.Intelligence packages.

Integration Options Overview​

ApproachBest ForTools the Programs Can Call
AI Webio.Intelligence web applications that connect to MCP servers through AI WebTools from every connected MCP server
MCP Core ServerMCP servers used by clients you don't control, such as third-party assistants or IDEsTools of that server only
StandaloneAny application that calls the model and manages its own toolsThe tools you register

Integration with AI Web​

AI Web runs Code Mode in the client, which is the component that sends requests to the model. It collects the tools from all connected MCP servers, so a single program can call tools from different servers.

When to Use AI Web
  • Your web application uses AI Web to connect to one or more MCP servers
  • The assistant needs to combine tools from different servers in one task

Implementation​

ai-web-code-mode.ts
import { IoAiWebFactory } from "@interopio/ai-web";
import { IoCodeModeFactory } from "@interopio/code-mode/browser";

const aiWeb = await IoAiWebFactory(io, {
  agentServer: {
    baseUrl: "https://agent.example.com",
  },
  codeMode: {
    factory: IoCodeModeFactory,
    config: {
      wasmLocation: "/quickjs/emscripten-module.wasm",
    },
  },
});

AI Web tells connected MCP servers that it runs Code Mode, so servers that also have Code Mode enabled send it their plain tool list instead.

Integration with MCP Core​

MCP Core runs Code Mode on the server and applies it to that server's own tools. Use it when the clients connecting to your server don't provide Code Mode themselves. MCP Core supports both transports: MCP HTTP in Node.js and MCP Web in the browser.

When to Use MCP Core
  • Your MCP server is used by third-party MCP clients, such as assistants or IDEs
  • You can't enable Code Mode in the client

Implementation​

mcp-core-code-mode.ts
import { IoCodeModeFactory } from "@interopio/code-mode/node";
import { IoIntelMCPCoreFactory } from "@interopio/mcp-core";

const mcpCore = await IoIntelMCPCoreFactory(io, {
  licenseKey,
  transport: { type: "http" },
  server: {
    name: "io-intelligence-mcp",
    codeMode: {
      factory: IoCodeModeFactory,
      config: {
        wasmLocation: quickJsWasmPath,
      },
    },
  },
});

Client Capability Handling​

When a client declares that it runs Code Mode itself, as AI Web does, MCP Core sends that client its plain tool list instead of the Code Mode tools. You can enable Code Mode on a server without conflicting with clients that already provide it.

Limitations​

MCP Core Limitations
  • Programs can call only the tools of that server, not tools from other servers the client connects to
  • Tools that open an interactive interface remain available directly, because code running in the sandbox cannot display a UI

Standalone Usage​

Use the @interopio/code-mode package directly when your application calls the model and manages its own tools. You register the tools with a Code Mode session and pass the returned Code Mode tools and system instruction to the model.

When to Use Standalone
  • Your application isn't built on io.Intelligence or io.Assist
  • You call the model through your own SDK or agent framework
  • You run the assistant in Node.js, for example in a backend service

Implementation​

standalone-code-mode.ts
import { IoCodeModeFactory } from "@interopio/code-mode/browser";

const codeMode = await IoCodeModeFactory({
  wasmLocation: "/quickjs/emscripten-module.wasm",
});

const session = codeMode.createSession();

session.setTools(hostTools);

const systemInstruction = codeMode.getSystemInstruction();
const metaTools = session.getLlmTools();

For Node.js, import IoCodeModeFactory from @interopio/code-mode/node and set wasmLocation to a file path. Standalone usage doesn't require AI Web, MCP Core, io.Assist, or io.Connect.

Limitations​

Standalone Limitations
  • You connect the Code Mode tools to your model SDK and route its tool calls yourself
  • You manage session lifetime for each model run

Decision Guide​

Choose AI Web If:​

  • Your application uses AI Web to talk to the assistant
  • The assistant needs tools from more than one MCP server

Choose MCP Core If:​

  • You provide an MCP server to clients you don't control
  • Those clients don't run Code Mode themselves

Choose Standalone If:​

  • Your application doesn't use io.Intelligence packages
  • You manage the model connection and tools yourself
Use One Code Mode Layer per Assistant

Enable Code Mode on only one layer that serves the same assistant. If several servers each run Code Mode, the assistant sees several sets of tool-discovery tools and cannot easily tell them apart. AI Web rejects a session in which more than one Code Mode provider is present.

Next Steps​