MCPManager - Hexos

Package: @hexos/runtime

Centralized manager for orchestrating multiple MCP server connections.

Handles lifecycle management for a pool of MCP servers, supporting both STDIO and SSE transports. Responsibilities include server initialization, tool discovery and caching, tool execution routing, and graceful shutdown.

Supports lazy initialization for servers that should only connect on first use, and implements retry logic with exponential backoff for connection and tool listing operations.

Tools from multiple servers are aggregated with server identification, allowing agents to specify which servers they can access via allowedMcpServers configuration.

Used by AgentRuntime to provide MCP tools to AgentDefinition instances. Creates MCPClient (STDIO) or MCPSSEClient (SSE) based on MCPServerConfig.

class MCPManager {
    constructor(servers: Record<string, MCPServerConfig>, options: MCPManagerOptions = {})
    initialize() => Promise<void>;
    getToolsForServers(serverNames: string[]) => MCPToolWithServer[];
    getAllTools() => MCPToolWithServer[];
    callTool(serverName: string, toolName: string, args: unknown) => Promise<unknown>;
    isServerConnected(name: string) => boolean;
    getConnectedServers() => string[];
    refreshTools(serverName: string) => Promise<MCPToolInfo[]>;
    shutdown() => Promise<void>;
}

constructor

(servers: RecordMCPServerConfig>, options: MCPManagerOptions = {}) => MCPManager

Create a new MCPManager instance.

initialize

() => Promise

Initialize all configured MCP servers that are not marked as lazy.

Connects to each non-lazy server in parallel, lists their tools, and caches the results. Servers marked with lazy: true are skipped and will be initialized on first use via ensureServerInitialized.

Idempotent - returns immediately if already initialized.

getToolsForServers

(serverNames: string[]) => MCPToolWithServer[]

Get all tools from the specified MCP servers.

Aggregates tools from multiple servers, adding serverName and originalName fields to each tool. Tool names are sanitized for LLM API compatibility.

Used by AgentRuntime when preparing tools for agents that specify allowedMcpServers.

getAllTools

() => MCPToolWithServer[]

Get all available tools from all connected servers.

Aggregates tools across all servers in the pool, adding serverName and originalName fields to each tool. Tool names are sanitized for LLM API compatibility.

callTool

(serverName: string, toolName: string, args: unknown) => Promise

Execute a tool on a specific MCP server.

Ensures the server is initialized (handles lazy servers), then routes the tool call to the appropriate client. Uses the original tool name (not sanitized) when calling the server.

isServerConnected

(name: string) => boolean

Check if a specific server is connected.

getConnectedServers

() => string[]

Get list of currently connected server names.

refreshTools

(serverName: string) => Promise<MCPToolInfo[]>

Refresh the tools cache for a specific server.

Re-queries the server for its tool list and updates the cache. Useful when a server’s tools may have changed dynamically.

shutdown

() => Promise

Shut down all MCP servers and clean up resources.

Disconnects all clients, clears the client and tools caches, and resets initialization state. Should be called during application shutdown to ensure graceful cleanup of MCP processes and connections.

MCPClient MCPManagerOptions