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
| Approach | Best For | Tools the Programs Can Call |
|---|---|---|
| AI Web | io.Intelligence web applications that connect to MCP servers through AI Web | Tools from every connected MCP server |
| MCP Core Server | MCP servers used by clients you don't control, such as third-party assistants or IDEs | Tools of that server only |
| Standalone | Any application that calls the model and manages its own tools | The 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.
- 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
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.
Tool Names, Refresh, and Sessions
AI Web uses plain MCP tool names without a server prefix; if servers expose duplicate names, only the first occurrence is kept. Use unique tool names across connected servers. Use the names returned by getTools for tool-definition lookups and match tool.name in toolFilter and onToolCall, not a server-prefixed name.
AI Web re-lists tools on MCP tool-list change notifications and rebuilds the Code Mode registry from enabled tools when preparing the next agent stream. Already-prepared runs retain their tool snapshots.
AI Web creates one Code Mode session per AI Web instance, shared across its agent streams. Code Mode sessions are not scoped by resourceId and do not enforce user permissions. Enforce authorization in the underlying tools or MCP server.
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.
- 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
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.
MCP Core creates one Code Mode session per MCP instance and removes it on instance cleanup. Tool additions and removals update that session's registry; each meta-tool call uses a fresh snapshot, while an in-flight execution keeps its existing snapshot. The model-visible meta-tool names remain unchanged.
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
Caller Context in AI Web and MCP Core
Caller-context forwarding is integration-specific. See AI Web CodeModeConfig for client-side limitations and MCP Core CodeModeConfig for request extras and verified per-user role checks. For direct host calls, see standalone caller context.
Other MCP Server Implementations
MCP Core performs Code Mode capability negotiation automatically. A server built with another MCP SDK can interoperate with AI Web, but its implementation must follow the same io.Intelligence convention:
- When AI Web has client-side Code Mode enabled, it sends
capabilities.experimental.codeMode: {}during MCP initialization. If the server also supports Code Mode, detect this non-null object and expose the original tools instead of wrapping them in server-side Code Mode. - When the client does not advertise that capability and the server exposes its own Code Mode, mark each Code Mode meta-tool in
tools/listwith_meta["io.interop/code-mode"] = true. AI Web uses this marker to recognize a server-side provider and detect conflicts.
The capability is under MCP's experimental field, not a standard MCP capability. Treat this as an io.Intelligence interoperability convention and verify compatibility when upgrading. The Code Mode package exports the metadata key for custom servers:
import { CodeModeToolMetaKey } from "@interopio/code-mode";
const clientCapability = clientCapabilities.experimental?.codeMode;
const clientUsesCodeMode = typeof clientCapability === "object" && clientCapability !== null;
// During initialization, use clientUsesCodeMode to choose plain tools or server-side Code Mode.
// On each server-side Code Mode meta-tool returned by tools/list:
const meta = { [CodeModeToolMetaKey]: true };
The Code Mode package does not add MCP SDK handlers or perform this negotiation for a custom server. Use MCP Core when you want the server-side integration and negotiation handled for you.
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.
- 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
import { IoCodeModeFactory } from "@interopio/code-mode/browser";
import type { IoCodeMode } from "@interopio/code-mode";
const hostTools: IoCodeMode.RuntimeTool[] = [
{
name: "search_orders",
description: "Search orders by query.",
inputSchema: {
type: "object",
properties: { query: { type: "string" } },
required: ["query"],
},
execute: async (args) => ({
content: [{ type: "text", text: `Results for ${String(args.query)}` }],
}),
},
];
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
- 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
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.
Troubleshooting Duplicate Providers
When AI Web finds more than one Code Mode provider while setting up tools, it throws an error like this. The names in brackets identify the MCP server providers and, if enabled, the AI Web client provider (ai-web):
Multiple code mode providers detected: [<provider names>]. Only one code mode provider is supported per session, otherwise the tools of one provider are virtualized again by the next. Disable code mode on the MCP server(s), or unset WebConfig.codeMode here.
Check both sides of the connection:
-
The agent backend may be running Code Mode on its MCP Core server. If AI Web should virtualize the tools for the assistant, disable the backend's
codeModeconfiguration. -
AI Web connects to the io.Connect MCP Web server by default because
mcp.ioIntel.web.enableddefaults totrue. If that server also exposes Code Mode, it is another provider. Disable Code Mode on that server, or disable its connection if you do not need its tools:mcp: {ioIntel: {web: { enabled: false },},}
Keep Code Mode enabled at only one layer for the assistant. Disabling the MCP Web connection removes that server's tools from AI Web as well.
Next Steps
- AI Web Code Mode configuration — Configure the AI Web integration
- MCP Core Code Mode configuration — Configure the MCP Core integration
- Code Mode API Reference — Set up the standalone integration
- Code Mode examples — Examples for all three approaches