DocsRuntimemcpIMCPClient
Package: @hexos/runtime

Common interface for Model Context Protocol (MCP) client implementations.

Defines the contract that all MCP clients must fulfill, regardless of the underlying transport mechanism (STDIO or SSE). Clients must handle connection lifecycle, tool discovery, and tool execution according to the MCP protocol specification.

Extends EventEmitter to support event-driven communication patterns such as error handling and connection state changes.

Implemented by MCPClient (STDIO transport) and MCPSSEClient (SSE transport). Managed by MCPManager for multi-server orchestration.

interface IMCPClient extends EventEmitter {
    connect(): Promise<void>;
    listTools(): Promise<MCPToolInfo[]>;
    callTool(name: string, args: unknown): Promise<unknown>;
    disconnect(): void;
    isConnected(): boolean;
}
  • Extends: EventEmitter

connect

() => Promise

Establish connection to the MCP server.

For STDIO clients, this spawns the child process and performs the MCP handshake (initialize + initialized notification). For SSE clients, this establishes the SSE connection and initializes the MCP client instance.

Must be idempotent - calling multiple times should not create duplicate connections.

listTools

() => Promise<MCPToolInfo[]>

Retrieve all tools available from the connected MCP server.

Sends a tools/list request via the MCP protocol and returns tool metadata including names, descriptions, and JSON schemas for input validation.

callTool

(name: string, args: unknown) => Promise

Execute a tool on the MCP server with the provided arguments.

Sends a tools/call request and returns the result. The MCP protocol returns content arrays (text/image/resource items), which implementations typically extract and parse into usable formats.

disconnect

() => void

Terminate the connection to the MCP server and clean up resources.

For STDIO clients, this kills the child process. For SSE clients, this closes the transport and MCP client instances. Should clear all pending requests and reset connection state.

isConnected

() => boolean

Check whether the client is currently connected to the MCP server.

DEFAULT_RETRYMcp