@interopio/mcp-core 0.1.0-beta.0

package/readme.md

@@ -0,0 +1,1091 @@
+# io.Intelligence MCP Core
+
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Installation](#installation)
+- [Core Concepts](#core-concepts)
+  - [MCP Server](#mcp-server)
+  - [Tools](#tools)
+  - [Client Capabilities](#client-capabilities)
+  - [Working Context Integration](#working-context-integration)
+- [API Reference](#api-reference)
+  - [IoIntelMCPCoreFactory](#iointelmcpcorefactory)
+  - [API Methods](#api-methods)
+  - [Configuration Types](#configuration-types)
+- [Configuration](#configuration)
+  - [License Key](#license-key)
+  - [Transport Configuration](#transport-configuration)
+  - [Server Configuration](#server-configuration)
+  - [Working Context Configuration](#working-context-configuration)
+  - [Application and Workspace Definition Requirements](#application-and-workspace-definition-requirements)
+- [Integration Options](#integration-options)
+  - [Standalone Usage](#standalone-usage)
+  - [With @interopio/mcp-stdio](#with-interopio-mcp-stdio)
+  - [With @interopio/mcp-http](#with-interopio-mcp-http)
+  - [With @interopio/mcp-web](#with-interopio-mcp-web)
+- [Tools](#tools-1)
+  - [System Tools](#system-tools)
+  - [Static Tools](#static-tools)
+  - [Dynamic Tools](#dynamic-tools)
+- [Examples](#examples)
+  - [Basic Server Setup](#basic-server-setup)
+  - [With Working Context](#with-working-context)
+  - [Custom Static Tools](#custom-static-tools)
+  - [Dynamic Tool Registration](#dynamic-tool-registration)
+
+---
+
+## Introduction
+
+`@interopio/mcp-core` is a TypeScript library that provides foundational functionality for building Model Context Protocol (MCP) servers within the io.Intelligence ecosystem. It enables seamless interoperability between applications and Large Language Models (LLMs) by providing interfaces and functions to create, register, and manage MCP tools.
+
+### Key Features
+
+- **MCP Server Creation**: Initialize and manage MCP server instances compliant with the MCP specification
+- **System Tools**: Pre-built tools for searching and starting applications and workspaces
+- **Static Tools**: Define tools in configuration that are automatically managed
+- **Dynamic Tools**: Register and unregister tools at runtime based on application state
+- **Working Context Integration**: Optional integration with `@interopio/intel-working-context` for enhanced context management
+- **Client Capability Detection**: Automatically adjusts available tools based on client capabilities
+- **Multi-Transport Support**: Works with STDIO, HTTP, and web-based transports
+
+### Target Audience
+
+Developers building MCP servers for io.Connect Desktop or io.Connect Browser platforms who need to expose application functionality to LLMs.
+
+---
+
+## Installation
+
+```bash
+npm install @interopio/mcp-core
+```
+
+### Requirements
+
+- Node.js 16 or higher
+- TypeScript 4.5 or higher
+- Valid io.Intelligence license key
+- io.Connect Desktop or io.Connect Browser instance
+
+---
+
+## Core Concepts
+
+### MCP Server
+
+An MCP server acts as a bridge between LLMs and io.Connect applications. The core library creates standard `McpServer` instances that can be connected to any MCP-compliant transport. Each server instance exposes tools that LLMs can invoke to interact with applications.
+
+### Tools
+
+Tools are functions that LLMs can call to perform actions. The library supports three types:
+
+- **System Tools**: Built-in tools for searching/starting applications and workspaces
+- **Static Tools**: Defined in configuration, automatically registered/unregistered based on interop availability
+- **Dynamic Tools**: Registered at runtime using `io.interop.register` with MCP-specific flags
+
+### Client Capabilities
+
+MCP clients declare capabilities such as `sampling` (for search operations) and `elicitation` (for user confirmations). The library adjusts available tools based on these capabilities:
+
+- Search tools require `sampling` capability
+- Start tools require `elicitation` capability
+- Working context tools are available unless client declares `experimental.workingContext`
+
+### Working Context Integration
+
+Optional integration with `@interopio/intel-working-context` enables the `io_connect_get_working_context` tool, allowing LLMs to retrieve the user's current business context (selected clients, portfolios, instruments, etc.).
+
+---
+
+## API Reference
+
+### IoIntelMCPCoreFactory
+
+```typescript
+IoIntelMCPCoreFactory(
+  io: IOConnectBrowser.API | IOConnectDesktop.API,
+  config: IoIntelMCPCore.Config
+): Promise<IoIntelMCPCore.API>
+```
+
+Factory function that initializes the MCP Core and returns an API for managing MCP instances.
+
+**Parameters:**
+
+- `io`: Initialized io.Connect API instance (Browser or Desktop)
+- `config`: Configuration object (see [Configuration](#configuration))
+
+**Returns:** Promise resolving to the MCP Core API
+
+**Throws:** Error if license key is invalid or expired (for trial licenses)
+
+### API Methods
+
+#### createMCPInstance
+
+```typescript
+createMCPInstance(
+  clientCapabilities: IoIntelMCPCore.ClientCapabilities
+): IoIntelMCPCore.MCPCore
+```
+
+Creates a new MCP server instance configured with tools appropriate for the client's capabilities.
+
+**Parameters:**
+
+- `clientCapabilities`: Object declaring what the client supports
+
+**Returns:** Object with `id` (string) and `instance` (McpServer)
+
+#### removeMCPInstance
+
+```typescript
+removeMCPInstance(id: string): void
+```
+
+Removes an MCP instance and cleans up associated resources.
+
+**Parameters:**
+
+- `id`: Unique identifier of the instance to remove
+
+### Configuration Types
+
+#### IoIntelMCPCore.Config
+
+```typescript
+interface Config {
+  licenseKey: string;
+  transport: McpTransportConfig;
+  server: McpServerConfig;
+  context?: WorkingContextConfig;
+}
+```
+
+#### McpTransportConfig
+
+```typescript
+interface McpTransportConfig {
+  type: "stdio" | "http" | "web";
+}
+```
+
+#### McpServerConfig
+
+```typescript
+interface McpServerConfig {
+  name: string;
+  title?: string;
+  tools?: {
+    dynamic?: DynamicToolsConfig;
+    static?: StaticToolsConfig;
+    system?: SystemToolConfig;
+  };
+}
+```
+
+#### ClientCapabilities
+
+```typescript
+interface ClientCapabilities {
+  sampling?: object;
+  elicitation?: object;
+  experimental?: {
+    workingContext?: boolean;
+  };
+  [key: string]: unknown;
+}
+```
+
+---
+
+## Configuration
+
+### License Key
+
+A valid io.Intelligence license key is **required** to use this package. The license is a signed JWT token provided by the io.Intelligence team.
+
+```typescript
+const config = {
+  licenseKey: "your-signed-jwt-token-here",
+  // ...
+};
+```
+
+**License Types:**
+
+- **Trial**: Must not be expired or initialization will fail
+- **Paid**: Will log warning if expired but continue operation
+
+### Transport Configuration
+
+Specifies the transport type for logging adjustment:
+
+```typescript
+transport: {
+  type: "stdio"; // Options: "stdio", "http", "web"
+}
+```
+
+**Important**: STDIO transport disables console logging to avoid interfering with MCP protocol messages.
+
+### Server Configuration
+
+#### Basic Configuration
+
+```typescript
+server: {
+  name: "my-mcp-server",
+  title: "My MCP Server"
+}
+```
+
+#### Tools Configuration
+
+```typescript
+server: {
+  name: "my-server",
+  tools: {
+    system: {
+      searchApps: { enabled: true },
+      searchWorkspaces: { enabled: true },
+      startApps: { enabled: true },
+      startWorkspaces: { enabled: true }
+    },
+    static: {
+      methods: [],
+      intents: []
+    },
+    dynamic: {
+      methods: { enabled: true }
+    }
+  }
+}
+```
+
+### Working Context Configuration
+
+```typescript
+context: {
+  factory: IoIntelWorkingContextFactory,
+  config: {
+    // Working context configuration
+  }
+}
+```
+
+When provided, automatically registers the `io_connect_get_working_context` tool.
+
+### Application and Workspace Definition Requirements
+
+For the system searching tools (`io_connect_search_applications` and `io_connect_search_workspaces`) to work effectively, application and workspace definitions in io.Connect must contain specific properties that enable the LLM to understand and explain their purpose.
+
+#### Application Definition Requirements
+
+**Required Properties:**
+
+- **`caption`**: A clear, descriptive explanation of what the application does. Without this property, the searching system tools cannot explain the application's functionality to the LLM, and the application will be filtered out from search results.
+
+**Optional Properties:**
+
+- **`customProperties.interop`**: Provides detailed information about the application's interoperability features. This property follows the `ApplicationInteropInfo` interface and can include:
+  - `methods`: Array of interop methods the application exposes
+  - `context`: Context data requirements and sources
+  - `intents`: Intents the application can handle
+
+**Example Application Definition:**
+
+```json
+{
+  "name": "proposal",
+  "type": "window",
+  "caption": "Manages and displays client proposals with detailed financial information",
+  "details": {
+    "url": "http://localhost:4100?intent=my_custom_intent"
+  },
+  "customProperties": {
+    "includeInWorkspaces": true,
+    "interop": {
+      "methods": [
+        {
+          "name": "get-proposal-data",
+          "description": "Get proposal data from the proposal app",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "proposalId": {
+                "type": "string",
+                "description": "The ID of the proposal to retrieve"
+              }
+            },
+            "required": ["proposalId"]
+          },
+          "outputSchema": {
+            "type": "object",
+            "properties": {
+              "proposalId": {
+                "type": "string",
+                "description": "The ID of the proposal"
+              },
+              "clientName": {
+                "type": "string",
+                "description": "The name of the client"
+              },
+              "amount": {
+                "type": "number",
+                "description": "The amount of the proposal"
+              },
+              "status": {
+                "type": "string",
+                "description": "The status of the proposal"
+              }
+            },
+            "required": ["proposalId", "clientName", "amount", "status"]
+          }
+        }
+      ],
+      "context": {
+        "sources": [
+          "initial-instance",
+          "global",
+          "channel",
+          "window",
+          "workspace"
+        ],
+        "description": "The app uses the context data to identify the proposal to display.",
+        "schema": {
+          "type": "object",
+          "properties": {
+            "proposalId": {
+              "type": "string",
+              "description": "The ID of the proposal"
+            },
+            "clientName": {
+              "type": "string",
+              "description": "The name of the client"
+            }
+          },
+          "required": ["proposalId", "clientName"]
+        }
+      },
+      "intents": [
+        {
+          "name": "my_custom_intent",
+          "description": "Handles requests to view proposal details.",
+          "contextTypes": ["fdc3.proposal"],
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "proposalId": {
+                "type": "string",
+                "description": "The ID of the proposal"
+              },
+              "clientName": {
+                "type": "string",
+                "description": "The name of the client"
+              }
+            },
+            "required": ["proposalId", "clientName"]
+          },
+          "outputSchema": {
+            "type": "object",
+            "properties": {
+              "status": {
+                "type": "string",
+                "description": "The status of the intent handling"
+              }
+            },
+            "required": ["status"]
+          },
+          "resultType": "fdc3.intentResult",
+          "customConfig": {},
+          "displayName": "View Proposal Details"
+        }
+      ]
+    }
+  },
+  "intents": [
+    {
+      "name": "my_custom_intent"
+    }
+  ]
+}
+```
+
+#### Workspace Definition Requirements
+
+**Required Properties:**
+
+- **`metadata.description`**: A clear explanation of what the workspace layout contains and its purpose. Without this property, the searching system tools cannot explain the workspace's functionality to the LLM, and the workspace will be excluded from search results.
+
+**Optional Properties:**
+
+- **`metadata.contextSchema`**: Defines the shape of the context object that the workspace uses. This JSON Schema describes the expected structure and properties of the workspace's context data.
+
+**Example Workspace Definition:**
+
+```json
+{
+  "name": "All Demos",
+  "type": "Workspace",
+  "metadata": {
+    "description": "A workspace layout containing all demo applications for comprehensive product demonstration.",
+    "contextSchema": {
+      "type": "object",
+      "properties": {
+        "clientId": {
+          "type": "string",
+          "description": "The client identifier to load across all applications"
+        },
+        "portfolioId": {
+          "type": "string",
+          "description": "The portfolio identifier to display"
+        }
+      },
+      "required": ["clientId"]
+    }
+  },
+  "components": []
+}
+```
+
+#### Impact on System Tools
+
+Applications and workspaces that don't meet the required property specifications will be automatically filtered out during the search process:
+
+- **Applications without `description`**: Cannot be analyzed by the LLM and will not appear in search results
+- **Applications with only global/channel context sources**: Filtered out as they lack specific interop capabilities
+- **Workspaces without `metadata.description`**: Cannot be explained to the LLM and will be excluded from workspace searches
+
+Providing optional properties like `customProperties.interop` for applications and `metadata.contextSchema` for workspaces enhances the LLM's ability to make informed decisions about which applications or workspaces best satisfy user intent.
+
+---
+
+## Integration Options
+
+### Standalone Usage
+
+Use directly with any MCP transport:
+
+```typescript
+import { IoIntelMCPCoreFactory } from "@interopio/mcp-core";
+import IOConnectBrowser from "@interopio/browser";
+
+const io = await IOConnectBrowser();
+
+const mcpApi = await IoIntelMCPCoreFactory(io, {
+  licenseKey: "your-license-key",
+  transport: { type: "web" },
+  server: { name: "my-server" },
+});
+
+const { instance } = mcpApi.createMCPInstance({
+  sampling: {},
+  elicitation: {},
+});
+
+// Connect instance to your transport
+```
+
+### With @interopio/mcp-stdio
+
+Provides standard input/output transport for console-based communication:
+
+```typescript
+import { IoIntelMCPStdioFactory } from "@interopio/mcp-stdio";
+
+const server = await IoIntelMCPStdioFactory(io, {
+  licenseKey: "your-license-key",
+  server: { name: "my-server" },
+});
+```
+
+### With @interopio/mcp-http
+
+Provides HTTP transport, preferred for io.Connect Desktop integration:
+
+```typescript
+import { IoIntelMCPHttpFactory } from "@interopio/mcp-http";
+
+const server = await IoIntelMCPHttpFactory(io, {
+  licenseKey: "your-license-key",
+  server: { name: "my-server" },
+  http: {
+    port: 3000,
+  },
+});
+```
+
+### With @interopio/mcp-web
+
+Provides web-based transport built on io.Connect Browser, preferred when frontend must be its own server:
+
+```typescript
+import { IoIntelMCPWebFactory } from "@interopio/mcp-web";
+
+const server = await IoIntelMCPWebFactory(io, {
+  licenseKey: "your-license-key",
+  server: { name: "my-server" },
+});
+```
+
+---
+
+## Tools
+
+### System Tools
+
+Five built-in system tools are available:
+
+#### io_connect_search_applications
+
+Discovers applications that can satisfy user intent and returns their interaction schemas.
+
+**Input:**
+
+```typescript
+{
+  userIntent: string; // Description of what user wants to accomplish
+}
+```
+
+**Output:**
+
+```typescript
+{
+  canSatisfyUserIntent: boolean,
+  summary: string,
+  nextSteps: string,
+  willSatisfyUserIntentBy: {
+    workspace?: { apps: ApplicationInfo[] },
+    apps?: ApplicationInfo[]
+  }
+}
+```
+
+**Requires:** Client `sampling` capability
+
+**Configuration:**
+
+```typescript
+system: {
+  searchApps: {
+    enabled: true,
+    overrides: {
+      name: "custom_search_apps",
+      description: "Custom description"
+    },
+    guard: (app) => app.name !== "internal-app"
+  }
+}
+```
+
+#### io_connect_search_workspaces
+
+Discovers saved workspaces that satisfy user intent.
+
+**Input:**
+
+```typescript
+{
+  userIntent: string;
+}
+```
+
+**Output:**
+
+```typescript
+{
+  canSatisfyUserIntent: boolean,
+  summary: string,
+  nextSteps: string,
+  willSatisfyUserIntentBy: {
+    workspace?: {
+      name: string,
+      description: string,
+      contextSchema: object
+    }
+  }
+}
+```
+
+**Requires:** Client `sampling` capability, io.Connect Workspaces API available
+
+**Configuration:**
+
+```typescript
+system: {
+  searchWorkspaces: {
+    enabled: true,
+    overrides: {
+      name: "custom_search_workspaces"
+    },
+    guard: (ws) => !ws.name.startsWith("_internal")
+  }
+}
+```
+
+#### io_connect_start_applications
+
+Launches applications with populated context data.
+
+**Input:**
+
+```typescript
+{
+  apps: Array<{
+    name: string;
+    initialInstanceContext?: object;
+    startOptions?: {
+      channelName?: string;
+      height?: number;
+      width?: number;
+      top?: number;
+      left?: number;
+    };
+    interop?: {
+      method?: { name: string; params?: object };
+      windowContext?: object;
+      intent?: {
+        name: string;
+        intentContextType?: string;
+        intentContextData?: object;
+      };
+    };
+  }>;
+}
+```
+
+**Output:**
+
+```typescript
+{
+  apps: Array<{
+    name: string;
+    status: "success" | "error";
+    responseData?: any;
+    errorMessage?: string;
+  }>;
+}
+```
+
+**Requires:** Client `elicitation` capability
+
+**Configuration:**
+
+```typescript
+system: {
+  startApps: {
+    enabled: true,
+    overrides: {
+      description: "Custom start description"
+    }
+  }
+}
+```
+
+#### io_connect_start_workspace
+
+Creates new workspace or restores existing workspace with context.
+
+**Input:**
+
+```typescript
+{
+  workspace:
+    | { name: string, context?: object } // Restore
+    | { apps: Array<...>, workspaceContext?: object } // Create
+}
+```
+
+**Output:**
+
+```typescript
+{
+  result: {
+    id: string,
+    status: "success" | "error",
+    errorMessage?: string,
+    methodInvocationResults?: Array<{
+      app: string,
+      invocationResult: any
+    }>
+  }
+}
+```
+
+**Requires:** Client `elicitation` capability, io.Connect Workspaces API available
+
+#### io_connect_get_working_context
+
+Retrieves current working context from io.Connect.
+
+**Input:** None
+
+**Output:**
+
+```typescript
+{
+  workingContext: Record<
+    string,
+    {
+      description?: string;
+      value: any;
+    }
+  >;
+}
+```
+
+**Requires:** Working context configured, client does not declare `experimental.workingContext`
+
+### Static Tools
+
+Static tools are defined in configuration and automatically managed by MCP Core.
+
+#### Static Method Tools
+
+```typescript
+static: {
+  methods: [
+    {
+      availability: "constant", // or "variable"
+      name: "my-tool-hello",
+      config: {
+        description: "Greets a person",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Person's name" },
+          },
+          required: ["name"],
+        },
+        outputSchema: {
+          type: "object",
+          properties: {
+            greeting: { type: "string" },
+          },
+          required: ["greeting"],
+        },
+      },
+      interop: {
+        methodName: "my_custom_method",
+        responseTimeoutMs: 5000,
+        allowedApplications: ["app1", "app2"],
+      },
+    },
+  ];
+}
+```
+
+**Availability:**
+
+- `constant`: Registered at startup, never changes
+- `variable`: Registered/unregistered automatically based on interop availability
+
+**Interop Application:**
+
+```typescript
+await io.interop.register(
+  {
+    name: "my_custom_method",
+  },
+  (args) => {
+    return { greeting: `Hello, ${args.name}` };
+  },
+);
+```
+
+#### Static Intent Tools
+
+```typescript
+static: {
+  intents: [
+    {
+      availability: "variable",
+      name: "my-intent-tool",
+      config: {
+        description: "Handles custom intent",
+        inputSchema: {
+          type: "object",
+          properties: {
+            type: { type: "string" },
+            data: { type: "object" },
+          },
+          required: ["type"],
+        },
+        outputSchema: {
+          /* ... */
+        },
+      },
+      interop: {
+        intentName: "my_custom_intent",
+        resolutionStrategy: "mcp", // or "io_connect"
+        allowedApplications: ["handler-app"],
+      },
+    },
+  ];
+}
+```
+
+**Resolution Strategies:**
+
+- `mcp`: Prefers app handlers over instance handlers
+- `io_connect`: Uses io.Connect's default resolution
+
+**Interop Application:**
+
+```typescript
+await io.intents.register({ intent: "my_custom_intent" }, (ctx) => {
+  return { result: `Processed ${ctx.data.type}` };
+});
+```
+
+### Dynamic Tools
+
+Dynamic tools are registered at runtime and managed entirely by the application.
+
+#### Registration
+
+```typescript
+await io.interop.register(
+  {
+    name: "awesome-method",
+    description: "An awesome MCP tool", // Required
+    flags: {
+      ioIntelMCPTool: {
+        name: "io_jpm_greeting_tool",
+        inputSchema: JSON.stringify({
+          $schema: "https://json-schema.org/draft-07/schema",
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Person's name" },
+          },
+          required: ["name"],
+        }),
+        outputSchema: JSON.stringify({
+          type: "object",
+          properties: {
+            greeting: { type: "string" },
+          },
+          required: ["greeting"],
+        }),
+      },
+    },
+  },
+  (args) => {
+    return { greeting: `Hello, ${args.name}` };
+  },
+);
+```
+
+#### Configuration Options
+
+```typescript
+interface InteropMethodToolConfig {
+  name: string;
+  inputSchema: string; // JSON Schema as string
+  outputSchema: string; // JSON Schema as string
+  title?: string;
+  annotations?: {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+  };
+  _meta?: Record<string, unknown>;
+  responseTimeoutMs?: number;
+}
+```
+
+#### Guard Function
+
+Filter which methods become MCP tools:
+
+```typescript
+dynamic: {
+  methods: {
+    enabled: true,
+    guard: (method, server) => {
+      return method.name.startsWith("mcp_") &&
+             server.applicationName === "allowed-app";
+    }
+  }
+}
+```
+
+---
+
+## Examples
+
+### Basic Server Setup
+
+```typescript
+import { IoIntelMCPCoreFactory } from "@interopio/mcp-core";
+import IOConnectBrowser from "@interopio/browser";
+
+const io = await IOConnectBrowser();
+
+const mcpApi = await IoIntelMCPCoreFactory(io, {
+  licenseKey: process.env.IO_LICENSE_KEY!,
+  transport: { type: "web" },
+  server: {
+    name: "basic-server",
+    title: "Basic MCP Server",
+  },
+});
+
+const { instance } = mcpApi.createMCPInstance({
+  sampling: {},
+  elicitation: {},
+});
+
+console.log("MCP server ready");
+```
+
+### With Working Context
+
+```typescript
+import { IoIntelMCPCoreFactory } from "@interopio/mcp-core";
+import { IoIntelWorkingContextFactory } from "@interopio/intel-working-context";
+import IOConnectBrowser from "@interopio/browser";
+
+const io = await IOConnectBrowser();
+
+const mcpApi = await IoIntelMCPCoreFactory(io, {
+  licenseKey: process.env.IO_LICENSE_KEY!,
+  transport: { type: "web" },
+  server: { name: "context-server" },
+  context: {
+    factory: IoIntelWorkingContextFactory,
+    config: {
+      trackers: {
+        fdc3: { enabled: true },
+      },
+    },
+  },
+});
+
+const { instance } = mcpApi.createMCPInstance({
+  sampling: {},
+  elicitation: {},
+});
+
+// io_connect_get_working_context tool is now available
+```
+
+### Custom Static Tools
+
+```typescript
+const mcpApi = await IoIntelMCPCoreFactory(io, {
+  licenseKey: process.env.IO_LICENSE_KEY!,
+  transport: { type: "http" },
+  server: {
+    name: "static-tools-server",
+    tools: {
+      static: {
+        methods: [
+          {
+            availability: "constant",
+            name: "get-client-portfolio",
+            config: {
+              description: "Retrieves portfolio for a client",
+              inputSchema: {
+                type: "object",
+                properties: {
+                  clientId: {
+                    type: "string",
+                    description: "Client identifier",
+                  },
+                },
+                required: ["clientId"],
+              },
+              outputSchema: {
+                type: "object",
+                properties: {
+                  portfolio: {
+                    type: "object",
+                    description: "Client portfolio data",
+                  },
+                },
+                required: ["portfolio"],
+              },
+            },
+            interop: {
+              methodName: "portfolio.get",
+              responseTimeoutMs: 3000,
+              allowedApplications: ["portfolio-service"],
+            },
+          },
+        ],
+      },
+    },
+  },
+});
+
+// Register the backend method
+await io.interop.register(
+  {
+    name: "portfolio.get",
+  },
+  async ({ clientId }) => {
+    const portfolio = await fetchPortfolio(clientId);
+    return { portfolio };
+  },
+);
+```
+
+### Dynamic Tool Registration
+
+```typescript
+const mcpApi = await IoIntelMCPCoreFactory(io, {
+  licenseKey: process.env.IO_LICENSE_KEY!,
+  transport: { type: "stdio" },
+  server: {
+    name: "dynamic-tools-server",
+    tools: {
+      dynamic: {
+        methods: {
+          enabled: true,
+          guard: (method) => method.name.startsWith("ai_"),
+        },
+      },
+    },
+  },
+});
+
+// Register dynamic tool
+await io.interop.register(
+  {
+    name: "ai_calculate_risk",
+    description: "Calculates risk score for a portfolio",
+    flags: {
+      ioIntelMCPTool: {
+        name: "calculate_risk",
+        inputSchema: JSON.stringify({
+          type: "object",
+          properties: {
+            portfolioId: { type: "string" },
+          },
+          required: ["portfolioId"],
+        }),
+        outputSchema: JSON.stringify({
+          type: "object",
+          properties: {
+            riskScore: { type: "number" },
+          },
+          required: ["riskScore"],
+        }),
+      },
+    },
+  },
+  async ({ portfolioId }) => {
+    const riskScore = await calculateRisk(portfolioId);
+    return { riskScore };
+  },
+);
+
+// Tool is automatically available to MCP clients
+```