Skip to main content

Examples

This page provides practical examples demonstrating how to use @interopio/mcp-web in various scenarios. Each example includes complete, runnable code with all necessary imports and configuration.

Basic Server Setup (Plugin)​

This example shows how to configure the MCP server as an io.Connect Browser plugin, which is the recommended approach for platform administrators. This provides centralized control over MCP capabilities across all connected clients.

import IOBrowserPlatform from "@interopio/browser-platform";
import { ServerFactory, IoIntelMCPWeb } from "@interopio/mcp-web";

// Define the server configuration
const mcpWebServerConfig: IoIntelMCPWeb.Server.Config = {
  licenseKey: process.env.IO_INTELLIGENCE_LICENSE_KEY,
  mcpCoreServer: {
    tools: {
      static: {
        methods: [
          {
            name: "getUserInfo",
            description: "Get current user information",
            inputSchema: {
              type: "object",
              properties: {},
            },
          },
        ],
      },
    },
  },
};

// Configure the platform with MCP Web as a plugin
const platformConfig = {
  plugins: {
    definitions: [
      {
        name: "io.MCPWeb",
        start: ServerFactory,
        critical: true,
        config: mcpWebServerConfig,
      },
    ],
  },
};

// Start the platform with the MCP server plugin
const { io, platform } = await IOBrowserPlatform(platformConfig);

Key Points:

  • The server runs as a plugin, automatically managed by the platform
  • Setting critical: true ensures the platform fails if the server cannot start
  • All applications connected to the platform can access the MCP server

Basic Server Setup (Direct)​

This example demonstrates starting an MCP server directly within a web application, giving you full control over the server lifecycle and configuration.

import IOBrowser from "@interopio/browser";
import { ServerFactory } from "@interopio/mcp-web";

async function startMCPServer() {
  // Initialize io.Connect Browser
  const io = await IOBrowser();

  // Start the MCP server with tool definitions
  await ServerFactory(io, {
    licenseKey: "your-license-key-here",
    mcpCoreServer: {
      tools: {
        static: {
          methods: [
            {
              name: "echo",
              description: "Echo back the input message",
              inputSchema: {
                type: "object",
                properties: {
                  message: { type: "string" },
                },
                required: ["message"],
              },
            },
          ],
        },
      },
    },
  });

  console.log("MCP Server started successfully");
}

startMCPServer();

Key Points:

  • The server is started directly in your application code
  • Useful for application-specific MCP capabilities
  • The server automatically registers the io.mcp.web.server interop method

Basic Client Setup​

This example shows how to connect to an MCP server from a web application, discover available tools, and invoke them.

import IOBrowser from "@interopio/browser";
import { ClientFactory } from "@interopio/mcp-web";

async function connectToMCPServer() {
  // Initialize io.Connect Browser
  const io = await IOBrowser();

  // Create the MCP client with basic capabilities
  const clientApi = await ClientFactory(io, {
    capabilities: {
      sampling: {},
      elicitation: {},
    },
  });

  // List available tools from the server
  const toolsResult = await clientApi.mcpClient.listTools();
  console.log("Available tools:", toolsResult.tools);

  // Call a specific tool
  const result = await clientApi.mcpClient.callTool({
    name: "echo",
    arguments: { message: "Hello, MCP!" },
  });

  console.log("Tool result:", result);
}

connectToMCPServer();

Key Points:

  • The client automatically discovers the MCP server via io.Connect Browser
  • Capabilities must be specified during client creation
  • The client provides full access to the MCP protocol operations

Client with Custom Capabilities​

This example demonstrates configuring a client with advanced capabilities and options, including strict capability enforcement and notification debouncing.

import IOBrowser from "@interopio/browser";
import { ClientFactory } from "@interopio/mcp-web";

async function advancedClientSetup() {
  // Initialize io.Connect Browser
  const io = await IOBrowser();

  // Create client with detailed configuration
  const clientApi = await ClientFactory(io, {
    // Enforce strict capability checking against server
    enforceStrictCapabilities: true,
    // Debounce high-frequency notifications to reduce overhead
    debouncedNotificationMethods: ["notifications/resources/list_changed"],
    capabilities: {
      sampling: {
        // Configure sampling parameters
        maxTokens: 1000,
        temperature: 0.7,
      },
      elicitation: {
        // Enable elicitation capability
        enabled: true,
      },
      experimental: {
        // Enable experimental features
        featureX: { enabled: true },
      },
    },
  });

  // Client is now ready with custom capabilities
  const resources = await clientApi.mcpClient.listResources();
  console.log("Available resources:", resources);
}

advancedClientSetup();

Key Points:

  • enforceStrictCapabilities ensures the client only uses capabilities supported by the server
  • Debouncing notification methods improves performance for high-frequency updates
  • Capabilities can include detailed configuration for sampling and experimental features

Self-Contained Application (Server and Client)​

A single web application can act as both MCP Server and MCP Client simultaneously — no external servers needed. This pattern is ideal for self-contained applications that expose capabilities and consume them within the same process.

import IOBrowser from "@interopio/browser";
import { ServerFactory, ClientFactory } from "@interopio/mcp-web";

async function startSelfContainedApp() {
  // 1. Initialize a single io.Connect Browser instance
  const io = await IOBrowser();

  // 2. Start the MCP Server — registers tools within this application
  await ServerFactory(io, {
    licenseKey: "your-license-key",
    mcpCoreServer: {
      tools: {
        static: {
          methods: [
            {
              name: "getPortfolioSummary",
              description: "Get a summary of the user's portfolio",
              inputSchema: {
                type: "object",
                properties: {
                  accountId: {
                    type: "string",
                    description: "The account identifier",
                  },
                },
                required: ["accountId"],
              },
            },
          ],
        },
      },
    },
  });

  // 3. Create the MCP Client — using the same `io` instance
  const clientApi = await ClientFactory(io, {
    capabilities: {
      sampling: {},
      elicitation: {},
    },
  });

  // 4. Discover tools exposed by the server
  const { tools } = await clientApi.mcpClient.listTools();
  console.log(
    "Available tools:",
    tools.map((t) => t.name),
  );

  // 5. Call a tool
  const result = await clientApi.mcpClient.callTool({
    name: "getPortfolioSummary",
    arguments: { accountId: "ACC-12345" },
  });

  console.log("Portfolio summary:", result.content);
}

startSelfContainedApp();

Key Points:

  • Both ServerFactory and ClientFactory receive the same io instance — this is what makes the pattern work
  • No external MCP server process is required; everything runs within a single web application
  • Works seamlessly with both io.Connect Browser and io.Connect Desktop environments
  • For architectures where the server and client are separate applications, see the Complete Integration Example below

Complete Integration Example​

This comprehensive example demonstrates a complete integration with both server and client applications, showing how tools and resources are exposed and consumed.

Application 1: MCP Server​

This application exposes MCP capabilities including tools and resources.

import IOBrowser from "@interopio/browser";
import { ServerFactory } from "@interopio/mcp-web";

async function startServer() {
  // Initialize io.Connect Browser with application identifier
  const io = await IOBrowser({
    application: "mcp-server-app",
  });

  // Start MCP server with tools and resources
  await ServerFactory(io, {
    licenseKey: "your-license-key",
    mcpCoreServer: {
      tools: {
        static: {
          methods: [
            {
              name: "getWeather",
              description: "Get weather for a location",
              inputSchema: {
                type: "object",
                properties: {
                  location: {
                    type: "string",
                    description: "City name",
                  },
                },
                required: ["location"],
              },
            },
          ],
        },
      },
      resources: {
        static: [
          {
            uri: "config://app-settings",
            name: "Application Settings",
            mimeType: "application/json",
          },
        ],
      },
    },
  });

  console.log("MCP Server is running");
}

startServer();

Application 2: MCP Client​

This application connects to the server, discovers available capabilities, and uses them.

import IOBrowser from "@interopio/browser";
import { ClientFactory } from "@interopio/mcp-web";

async function startClient() {
  // Initialize io.Connect Browser with application identifier
  const io = await IOBrowser({
    application: "mcp-client-app",
  });

  // Create MCP client
  const clientApi = await ClientFactory(io, {
    enforceStrictCapabilities: true,
    capabilities: {
      sampling: {},
      elicitation: {},
    },
  });

  // Discover available tools
  const { tools } = await clientApi.mcpClient.listTools();
  console.log(
    "Available tools:",
    tools.map((t) => t.name),
  );

  // Call the weather tool
  const weatherResult = await clientApi.mcpClient.callTool({
    name: "getWeather",
    arguments: { location: "London" },
  });
  console.log("Weather result:", weatherResult.content);

  // List available resources
  const { resources } = await clientApi.mcpClient.listResources();
  console.log(
    "Available resources:",
    resources.map((r) => r.uri),
  );

  // Read a resource
  const settingsResource = await clientApi.mcpClient.readResource({
    uri: "config://app-settings",
  });
  console.log("Settings:", settingsResource.contents);
}

startClient();

Key Points:

  • The server exposes both tools (getWeather) and resources (app-settings)
  • The client discovers capabilities dynamically using listTools() and listResources()
  • Both applications use io.Connect Browser for communication
  • The applications are identified by different application names for clarity
  • All communication happens through the io.Connect Browser interop system

Next Steps​

After reviewing these examples, you may want to: