Skip to main content

Overview

@interopio/mcp-web is a TypeScript library that enables web applications to serve and consume Model Context Protocol (MCP) capabilities within a browser environment. The package provides two distinct functionalities:

  • MCP Server - Delivers the capabilities of @interopio/mcp-core from web applications, without requiring a traditional Node.js server environment
  • MCP Client - Allows web applications to connect as MCP clients to the MCP Server component

Key Features​

  • Web-based MCP transport implementation using io.Connect Browser
  • Seamless integration with io.Connect Browser as a plugin or standalone
  • Full MCP specification compliance
  • TypeScript support with comprehensive type definitions
  • Built-in schema validation and error handling
  • Support for MCP client capabilities including sampling, elicitation, extensions, and experimental fields

Target Audience​

This package is designed for developers building web applications in io.Connect Browser environments who need to expose or consume MCP capabilities without running traditional server infrastructure.

Installation​

Install the package using npm:

npm install @interopio/mcp-web

Or using yarn:

yarn add @interopio/mcp-web

Requirements​

The following peer dependencies are required:

  • @interopio/browser or @interopio/desktop - io.Connect Browser/Desktop API
  • @interopio/mcp-core - Core MCP implementation
  • @modelcontextprotocol/sdk - Model Context Protocol SDK

Core Concepts​

Web Transport​

Traditional MCP implementations use standard I/O or HTTP-based transports. @interopio/mcp-web implements a custom web transport layer using io.Connect Browser's interop system, enabling MCP communication between web applications without requiring external servers.

The web transport provides:

  • Bidirectional communication between MCP clients and servers
  • Instance-specific connections supporting multiple clients
  • Built-in message routing and error handling
  • Integration with io.Connect Browser's security and lifecycle management

Server vs Client​

Understanding the distinction between Server and Client is essential for proper implementation:

MCP Server

  • Exposes MCP capabilities (tools, resources, prompts) that can be consumed by MCP clients
  • Uses @interopio/mcp-core internally to provide these capabilities
  • Registers the interop method io.mcp.web.server to receive client requests
  • Can be deployed as an io.Connect Browser plugin or within individual applications
  • Manages capability lifecycle and client connections

MCP Client

  • Connects to an MCP server to discover and invoke available capabilities
  • Implements the MCP client specification from @modelcontextprotocol/sdk
  • Registers the interop method io.mcp.web.client to receive server responses
  • Advertises its own capabilities to the server during initialization
  • Provides methods to list and invoke tools, resources, and prompts

Single Application as Both Server and Client​

A single application can be configured to function as both an MCP Server and an MCP Client simultaneously. This configuration is particularly useful when you need the AI Assistant to have access to all available tools and capabilities without relying on external MCP servers.

Benefits of this approach:

  • The application can expose its own capabilities as an MCP Server while also consuming them through the MCP Client
  • All tools and capabilities remain within a single application context
  • No dependency on external MCP server processes or infrastructure
  • Simplified deployment and maintenance

Supported platforms:

This approach works seamlessly with both io.Connect Browser and io.Connect Desktop environments, providing flexibility in deployment scenarios.

Typical use cases:

  • Self-contained applications that need to provide MCP capabilities to embedded AI Assistants
  • Development and testing environments where external servers are not desired
  • Applications requiring tight integration between capability providers and consumers
  • Scenarios where security or network policies restrict external MCP connections

At a glance, the pattern looks like this:

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

// One io instance powers both roles
const io = await IOBrowser();

// Start the MCP Server (registers tools, resources, prompts)
await ServerFactory(io, {
  licenseKey: "your-license-key",
  mcpCoreServer: { tools: { static: { methods: [/* ... */] } } },
});

// Create the MCP Client using the same io instance
const { mcpClient } = await ClientFactory(io, {
  capabilities: {
    sampling: {},
    elicitation: {},
    extensions: {
      "io.modelcontextprotocol/ui": {
        mimeTypes: ["text/html;profile=mcp-app"],
      },
    },
  },
});

// Client can now discover and call the server's tools
const { tools } = await mcpClient.listTools();

See the Self-Contained Application example for a complete, runnable version.

io.Connect Integration​

The package leverages io.Connect Browser's interop methods for communication:

Server Registration

The server registers the method io.mcp.web.server to receive client requests. This method handles:

  • Client initialization and capability negotiation
  • Tool invocations
  • Resource reads
  • Prompt requests
  • Server notifications

Client Registration

The client registers the method io.mcp.web.client to receive server responses. This method handles:

  • Server responses to client requests
  • Server-initiated notifications
  • Resource and prompt updates
  • Capability changes

Communication Flow

Communication is instance-specific, supporting multiple client connections:

  1. Client initiates connection by invoking the server's registered method
  2. Server and client exchange capability information
  3. Client can discover available tools, resources, and prompts
  4. Client invokes capabilities through the web transport
  5. Server processes requests and returns responses
  6. Both parties can send notifications as needed

This architecture ensures that MCP communication is fully integrated with io.Connect Browser's security model, instance management, and lifecycle controls.

Next Steps​

  • Explore the Server API to learn how to create and configure MCP servers
  • Review the Client API to understand how to connect and consume MCP capabilities
  • Check out Examples for common implementation patterns
  • See AI Web Overview if you want to consume MCP capabilities from a custom assistant frontend
  • See io.Assist NG Overview if you want the ready-made Angular assistant on top of MCP-enabled infrastructure