Configuration

This page documents the configuration types used by IoAiWebFactory.

---

IoAiWeb.WebConfig

Top-level configuration for AI Web.

interface WebConfig {
    mcp?: MCPConfig;
    agentServer: AgentServerConfig;
    context?: WorkingContextConfig;
    codeMode?: CodeModeConfig;
}

Property	Type	Required	Description
agentServer	AgentServerConfig	Yes	Connection details for the backend implementing the io.Intelligence Agent Protocol
mcp	MCPConfig	No	MCP client and server connection settings
context	WorkingContextConfig	No	Working Context integration
codeMode	CodeModeConfig	No	Code Mode integration for model-facing tool virtualization

Minimal Configuration

const config: IoAiWeb.WebConfig = {
    agentServer: {
        baseUrl: "http://localhost:4111",
    },
};

---

AgentServerConfig

Connection settings for the agent server.

interface AgentServerConfig {
    baseUrl: string;
    retries?: number;
    backoffMs?: number;
    maxBackoffMs?: number;
    headers?: Record<string, string>;
    abortSignal?: AbortSignal;
    credentials?: "omit" | "same-origin" | "include";
}

Property	Type	Required	Description
baseUrl	string	Yes	Base URL for the backend that implements the io.Intelligence Agent Protocol
retries	number	No	Retry count for server requests
backoffMs	number	No	Initial backoff delay in milliseconds
maxBackoffMs	number	No	Maximum backoff delay in milliseconds
headers	Record<string, string>	No	Additional request headers such as Authorization
abortSignal	AbortSignal	No	Shared abort signal for requests
credentials	"omit" | "same-origin" | "include"	No	Fetch credentials mode

See Agent Protocol for the route and streaming contract AI Web expects at this base URL.

Example

agentServer: {
  baseUrl: "https://agents.example.com",
  retries: 3,
  backoffMs: 1000,
  maxBackoffMs: 10000,
  headers: {
    Authorization: "Bearer user-token",
  },
  credentials: "omit",
}

---

MCPConfig

Controls MCP connections and MCP Apps behavior.

interface MCPConfig {
    clientsConfig: MCPClientConfig;
    ioIntel?: {
        remote?: MCPRemoteServerConfig;
        web?: {
            enabled?: boolean;
            hasPriority?: boolean;
        };
    };
    remoteServers?: MCPRemoteServerConfig[];
    mcpApps?: McpApps.Config;
}

Property	Type	Required	Description
clientsConfig	MCPClientConfig	Yes	MCP client capabilities and behavior
ioIntel.remote	MCPRemoteServerConfig	No	Remote Streamable HTTP connection to the io.Intelligence MCP server
ioIntel.web	{ enabled?: boolean; hasPriority?: boolean }	No	io.Connect web transport settings for the io.Intelligence MCP server
remoteServers	MCPRemoteServerConfig[]	No	Additional remote MCP servers
mcpApps	IoAiWeb.McpApps.Config	No	MCP Apps rendering settings

Notes

• Use ioIntel.web when the io.Intelligence MCP server is reachable through the io.Connect environment
• Use ioIntel.remote when the same server is exposed over Streamable HTTP
• Use remoteServers for third-party or additional MCP servers
• Remote MCP server names must be unique

Example

mcp: {
  clientsConfig: {
    capabilities: {},
  },
  ioIntel: {
    web: {
      hasPriority: false,
    },
    remote: {
      streamableHttp: {
        url: "http://localhost:8989/mcp",
        name: "primary-remote-server",
      },
    },
  },
  remoteServers: [
    {
      streamableHttp: {
        url: "http://localhost:8081/mcp",
        name: "secondary-mcp-server",
      },
    },
  ],
}

---

MCPClientConfig

Defines client capabilities advertised to MCP servers.

interface MCPClientConfig {
    enforceStrictCapabilities?: boolean;
    debouncedNotificationMethods?: string[];
    capabilities: {
        sampling?: {
            handler?: (serverName: string, params: SamplingRequestParams) => Promise<SamplingSuccessResponse | SamplingErrorResponse>;
        };
        elicitation?: {
            handler?: (serverName: string, params: ElicitationRequestParams) => Promise<ElicitationResponse>;
        };
        extensions?: {
            "io.modelcontextprotocol/ui"?: {
                mimeTypes: string[];
            };
            [key: string]: any;
        };
        experimental?: Record<string, any>;
    };
}

Property	Type	Required	Description
enforceStrictCapabilities	boolean	No	Enables stricter capability validation
debouncedNotificationMethods	string[]	No	Notification methods to debounce
capabilities.sampling.handler	function	No	Handles sampling requests from MCP servers
capabilities.elicitation.handler	function	No	Handles elicitation requests from MCP servers
capabilities.extensions	object	No	Extension capability metadata, including MCP App UI support
capabilities.experimental	object	No	Custom experimental capability declarations

UI Extension Example

To advertise MCP App UI support, expose the UI extension capability:

clientsConfig: {
  capabilities: {
    extensions: {
      "io.modelcontextprotocol/ui": {
        mimeTypes: ["text/html;profile=mcp-app"],
      },
    },
  },
}

---

MCPRemoteServerConfig

Streamable HTTP configuration for a remote MCP server.

interface MCPRemoteServerConfig {
    streamableHttp: {
        url: string;
        name: string;
        options?: StreamableHTTPClientTransportOptions;
    };
}

Property	Type	Required	Description
streamableHttp.url	string	Yes	Full MCP endpoint URL
streamableHttp.name	string	Yes	Unique logical name for the server
streamableHttp.options	StreamableHTTPClientTransportOptions	No	Low-level transport options

---

WorkingContextConfig

Enables Working Context integration.

interface WorkingContextConfig {
    factory: IoIntelWorkingContextFactoryFunction;
    config?: IoIntelWorkingContext.Config;
}

Property	Type	Required	Description
factory	IoIntelWorkingContextFactoryFunction	Yes	Factory used to initialize Working Context
config	IoIntelWorkingContext.Config	No	Working Context schema and runtime options

Example

import { IoIntelWorkingContextFactory } from "@interopio/working-context";

context: {
  factory: IoIntelWorkingContextFactory,
  config: {
    schema: {
      clientId: {
        type: "string",
        source: {
          context: {
            location: { workspace: { target: "my" } },
            path: "clientId",
          },
        },
      },
    },
  },
}

For the schema model itself, see Working Context Schema Configuration.

---

CodeModeConfig

Enables Code Mode in AI Web. Configure this at the client when AI Web owns the LLM request or connects to multiple MCP servers. AI Web maintains a Code Mode session for the client and automatically declares capabilities.experimental.codeMode to connected @interopio/mcp-core servers.

The session belongs to the AI Web instance. Code Mode sessions are not scoped by resourceId and do not enforce user permissions. Enforce authorization in the underlying tools or MCP server. Tools retain their plain MCP names, and duplicate names across servers keep only the first occurrence. MCP tool-list change notifications refresh the catalog; the next agent stream rebuilds the session registry from enabled tools. See Tool Names, Refresh, and Sessions for lifecycle details.

interface CodeModeConfig {
    factory: IoCodeModeFactoryFunction;
    config: IoCodeMode.Config;
}

Property	Type	Required	Description
factory	IoCodeModeFactoryFunction	Yes	The browser Code Mode factory, imported from @interopio/code-mode/browser.
config	IoCodeMode.Config	Yes	QuickJS WASM location, resource limits, and optional tool policies.

Example

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

const config: IoAiWeb.WebConfig = {
    agentServer: {
        baseUrl: "http://localhost:4111",
    },
    codeMode: {
        factory: IoCodeModeFactory,
        config: {
            wasmLocation: "/quickjs/emscripten-module.wasm",
        },
    },
};

One Owner per Client

When AI Web connects to multiple MCP servers, configure Code Mode in AI Web rather than on each server. This lets the client virtualize the combined tool catalog once and avoids duplicate getTools, getToolDefinition, and executeCode meta-tools in the model-facing tool list.

Caller Context

AI Web passes the tool-call cancellation signal to Code Mode through ExecuteOptions.signal, but does not set ExecuteOptions.context. Consequently, config.interceptors.onToolCall receives callContext: undefined; it does not receive the user, role, resourceId, or thread ID. There is no public AI Web per-run option for injecting arbitrary Code Mode caller context.

For per-user role checks, authenticate the MCP request and resolve the role on the server from verified credentials. Supplying a role in tool arguments or Working Context does not establish authorization. If your host directly invokes the standalone Code Mode API, it can supply execute(args, { context }); this is not an AI Web stream option.

See MCP Core caller context for server-side request extras and a verified-role interceptor example.

See Code Mode Configuration for the IoCodeMode.Config options and Code Mode Overview for integration ownership guidance.

---

McpApps.Config

Controls how MCP Apps are rendered.

interface Config {
    sandboxProxyUrl: string;
    displayMode?: "inline" | "workspace";
}

Property	Type	Required	Description
sandboxProxyUrl	string	Yes	URL of the sandbox proxy HTML page served by the host application
displayMode	"inline" | "workspace"	No	Preferred display mode. When omitted, AI Web resolves the mode at runtime

Practical Notes

• The sandbox proxy is required for MCP Apps
• The proxy forwards messages between the host and a sandboxed guest iframe
• Workspace mode depends on io.Connect Workspace support

Example

mcp: {
  clientsConfig: {
    capabilities: {
      extensions: {
        "io.modelcontextprotocol/ui": {
          mimeTypes: ["text/html;profile=mcp-app"],
        },
      },
    },
  },
  mcpApps: {
    sandboxProxyUrl: "http://localhost:5206/index.html",
    displayMode: "workspace",
  },
}