Client API

The Client API enables web applications to connect to MCP servers and consume their capabilities. This page provides a complete reference for creating and configuring MCP clients in web environments.

ClientFactory

Factory function that creates an MCP client instance and establishes a connection to the MCP server.

type IoIntelMCPWebClientFactoryFunction = (
  io: IOConnectBrowser.API | IOConnectDesktop.API,
  config: IoIntelMCPWeb.Client.Config,
) => Promise<IoIntelMCPWeb.Client.API>;

Parameters:

Parameter	Type	Description
`io`	`IOConnectBrowser.API` \| `IOConnectDesktop.API`	io.Connect Browser or Desktop API instance
`config`	`IoIntelMCPWeb.Client.Config`	Client configuration object specifying capabilities and behavior

Returns: Promise<IoIntelMCPWeb.Client.API> - Promise that resolves to the initialized Client API

Example:

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

const io = await IOBrowser();

const clientApi = await ClientFactory(io, {
  capabilities: {
    sampling: {},
    elicitation: {},
  },
});

// Client is now connected and ready to use
const tools = await clientApi.mcpClient.listTools();

Client Configuration

The client configuration interface defines how the MCP client behaves and what capabilities it advertises to the server.

interface Config {
  enforceStrictCapabilities?: boolean;
  debouncedNotificationMethods?: string[];
  capabilities: {
    sampling?: Record<string, any>;
    elicitation?: Record<string, any>;
    extensions?: Record<string, any>;
    experimental?: Record<string, any>;
  };
}

Properties

`enforceStrictCapabilities`

Type: boolean
Default: true
Required: No

When true, the client enforces strict capability checking against the server's advertised capabilities. This ensures that the client only attempts to use features that the server explicitly supports, preventing runtime errors from unsupported operations.

`debouncedNotificationMethods`

Type: string[]
Default: []
Required: No

Array of notification method names that should be debounced. This is useful for high-frequency notifications that would otherwise trigger excessive processing. Debouncing reduces the number of times the notification handler is called, improving performance.

Example:

debouncedNotificationMethods: [
  "notifications/resources/list_changed",
  "notifications/tools/list_changed"
]

`capabilities`

Type: object
Required: Yes

Object defining the client's capabilities that will be advertised to the server during initialization.

`capabilities.sampling`

Type: Record<string, any>
Required: No

Configuration for sampling capabilities. The sampling capability allows the client to request content generation from the server with specific parameters.

Example:

capabilities: {
  sampling: {
    maxTokens: 1000,
    temperature: 0.7
  }
}

`capabilities.elicitation`

Type: Record<string, any>
Required: No

Configuration for elicitation capabilities. The elicitation capability enables the client to request interactive prompts or user input flows from the server.

Example:

capabilities: {
  elicitation: {
    enabled: true
  }
}

`capabilities.experimental`

Type: Record<string, any>
Required: No

Configuration for experimental features. This allows the client to opt into non-standard or preview capabilities that may not be part of the official MCP specification.

Example:

capabilities: {
  experimental: {
    featureX: { enabled: true }
  }
}

`capabilities.extensions`

Type: Record<string, any>
Required: No

Extension capabilities allow the client to advertise additional protocol-specific support, such as MCP App UI metadata.

Example:

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

Configuration Rules

The capabilities object must be provided and contain at least one capability definition
enforceStrictCapabilities defaults to true for safer operation and better error prevention
Debounced notification methods help reduce redundant notifications for high-frequency events
Capability configurations are passed directly to the MCP client initialization

Client Configuration Options

Complete reference table for all client configuration options:

Option	Type	Required	Default	Description
`capabilities`	`object`	Yes	-	Client capabilities to advertise to the server
`capabilities.sampling`	`object`	No	-	Sampling capability configuration for content generation
`capabilities.elicitation`	`object`	No	-	Elicitation capability configuration for interactive prompts
`capabilities.extensions`	`object`	No	-	Extension capability metadata, including UI-related capabilities
`capabilities.experimental`	`object`	No	-	Experimental features configuration for preview capabilities
`enforceStrictCapabilities`	`boolean`	No	`true`	Enforce strict capability checking against server capabilities
`debouncedNotificationMethods`	`string[]`	No	`[]`	Array of notification method names to debounce for performance

Client API

The Client API provides access to the underlying MCP client instance, which implements the full Model Context Protocol client specification.

interface API {
  mcpClient: MCPClient;
}

Properties

`mcpClient`

Type: MCPClient (from @modelcontextprotocol/sdk)

The MCP client instance with full access to all MCP client capabilities. This client can be used to discover and invoke tools, read resources, retrieve prompts, and perform all other MCP client operations.

Common Client Operations

The following sections demonstrate common operations performed using the MCP client.

listTools()

Retrieve a list of all tools available from the connected MCP server.

const toolsResult = await clientApi.mcpClient.listTools();

console.log("Available tools:", toolsResult.tools);

// Example output structure:
// {
//   tools: [
//     {
//       name: "calculate",
//       description: "Perform mathematical calculations",
//       inputSchema: { ... }
//     }
//   ]
// }

callTool()

Invoke a specific tool with the required arguments.

const result = await clientApi.mcpClient.callTool({
  name: "calculate",
  arguments: {
    operation: "add",
    a: 5,
    b: 3
  }
});

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

// The result contains the tool's response
// Structure depends on the tool's implementation

listResources()

Retrieve a list of all resources available from the connected MCP server.

const resourcesResult = await clientApi.mcpClient.listResources();

console.log("Available resources:", resourcesResult.resources);

// Example output structure:
// {
//   resources: [
//     {
//       uri: "config://app-settings",
//       name: "Application Settings",
//       mimeType: "application/json"
//     }
//   ]
// }

readResource()

Read the contents of a specific resource by its URI.

const resource = await clientApi.mcpClient.readResource({
  uri: "config://app-settings"
});

console.log("Resource contents:", resource.contents);

// The contents structure depends on the resource's mimeType
// JSON resources will be parsed, text resources returned as strings

listPrompts()

Retrieve a list of all prompts available from the connected MCP server.

const promptsResult = await clientApi.mcpClient.listPrompts();

console.log("Available prompts:", promptsResult.prompts);

// Example output structure:
// {
//   prompts: [
//     {
//       name: "greeting",
//       description: "Generate a personalized greeting",
//       arguments: [...]
//     }
//   ]
// }

getPrompt()

Retrieve a specific prompt with arguments.

const prompt = await clientApi.mcpClient.getPrompt({
  name: "greeting",
  arguments: {
    userName: "John",
    timeOfDay: "morning"
  }
});

console.log("Prompt result:", prompt);

// The prompt result contains the generated prompt content
// with the arguments interpolated according to the prompt's template

Complete Example

The following example demonstrates a complete client setup with multiple operations:

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

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

  // Create and configure the MCP client
  const clientApi = await ClientFactory(io, {
    enforceStrictCapabilities: true,
    debouncedNotificationMethods: [
      "notifications/resources/list_changed"
    ],
    capabilities: {
      sampling: {
        maxTokens: 1000
      },
      elicitation: {
        enabled: true
      }
    }
  });

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

  // Call a tool
  if (tools.length > 0) {
    const result = await clientApi.mcpClient.callTool({
      name: tools[0].name,
      arguments: {} // Provide appropriate arguments
    });
    console.log("Tool result:", result.content);
  }

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

  if (resources.length > 0) {
    const resource = await clientApi.mcpClient.readResource({
      uri: resources[0].uri
    });
    console.log("Resource contents:", resource.contents);
  }

  // Discover and use prompts
  const { prompts } = await clientApi.mcpClient.listPrompts();
  console.log("Available prompts:", prompts.map(p => p.name));

  if (prompts.length > 0) {
    const prompt = await clientApi.mcpClient.getPrompt({
      name: prompts[0].name,
      arguments: {} // Provide appropriate arguments
    });
    console.log("Prompt:", prompt);
  }
}

mcpClientExample().catch(console.error);

Error Handling

When using the MCP client, handle errors appropriately to ensure robust application behavior:

try {
  const result = await clientApi.mcpClient.callTool({
    name: "nonexistent-tool",
    arguments: {}
  });
} catch (error) {
  if (error.code === "METHOD_NOT_FOUND") {
    console.error("Tool does not exist");
  } else if (error.code === "INVALID_PARAMS") {
    console.error("Invalid tool arguments provided");
  } else {
    console.error("Tool invocation failed:", error.message);
  }
}

Server API - Documentation for the MCP Web Server
MCP Core - Core MCP implementation
Examples - Practical usage examples

ClientFactory​

Client Configuration​

Properties​

enforceStrictCapabilities​

debouncedNotificationMethods​

capabilities​

capabilities.sampling​

capabilities.elicitation​

capabilities.experimental​

capabilities.extensions​

Configuration Rules​

Client Configuration Options​

Client API​

Properties​

mcpClient​

Common Client Operations​

listTools()​

callTool()​

listResources()​

readResource()​

listPrompts()​

getPrompt()​

Complete Example​

Error Handling​

Related Resources​

ClientFactory

Client Configuration

Properties

`enforceStrictCapabilities`

`debouncedNotificationMethods`

`capabilities`

`capabilities.sampling`

`capabilities.elicitation`

`capabilities.experimental`

`capabilities.extensions`

Configuration Rules

Client Configuration Options

Client API

Properties

`mcpClient`

Common Client Operations

listTools()

callTool()

listResources()

readResource()

listPrompts()

getPrompt()

Complete Example

Error Handling

Related Resources