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;
}

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

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.

---

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",
  },
}