MCP Module Overview

The MCP (Model Context Protocol) module manages connections to external MCP servers, tool discovery, format conversion, and call execution. This module uses a layered architecture with the core in the main process, exposed to the renderer process via IPC.

Architecture Diagram

graph TB
    subgraph Renderer["Renderer Process"]
        McpPage["McpServersPage"]
        McpForm["McpServerForm"]
        McpManage["McpManageDialog"]
        UseMcp["useMcpMode Hook"]
        UseMgmt["useMcpManagement Hook"]
    end

    subgraph Main["Main Process"]
        McpRouter["McpRouter<br/>(IPC Routing)"]
        McpService["McpService<br/>(Connection Pool)"]
        ToolsLoader["ToolsLoader<br/>(Format Conversion)"]
        DepCheck["DependencyCheckService<br/>(Dependency Check)"]

        subgraph Transports["Transport Layer"]
            Stdio["StdioClientTransport"]
            SSE["SSEClientTransport"]
            HTTP["StreamableHTTPClientTransport"]
        end

        subgraph TinyElf["TinyElf Engine"]
            McpAdapter["McpToolAdapter<br/>(ITool Wrapping)"]
            DirectAdapter["DirectMcpToolAdapter<br/>(Built-in Servers)"]
            Tracker["McpProcessTracker<br/>(Process Tracking)"]
        end
    end

    subgraph Worker["Worker Thread"]
        McpWorker["mcp.worker.ts<br/>(CLI Bridging)"]
    end

    subgraph External["External"]
        MCP1["MCP Server A<br/>(stdio)"]
        MCP2["MCP Server B<br/>(SSE/HTTP)"]
        ClaudeCLI["claude CLI"]
    end

    McpPage -->|IPC| McpRouter
    McpRouter --> McpService
    McpRouter --> DepCheck
    McpService --> Stdio
    McpService --> SSE
    McpService --> HTTP
    Stdio --> MCP1
    SSE --> MCP2
    HTTP --> MCP2
    McpService --> ToolsLoader
    McpService --> McpAdapter
    McpAdapter --> McpService
    DirectAdapter --> MCP1
    Tracker --> DirectAdapter
    McpWorker --> ClaudeCLI

Key Files

File	Path	Responsibility
McpService.ts	desktop/app/main/services/capabilities/tools/mcp-users/	Connection pool management, client lifecycle, tool caching
ToolsLoader.ts	desktop/app/main/services/capabilities/tools/mcp-users/	Convert MCP tools to OpenAI/Anthropic/Gemini formats
DependencyCheckService.ts	desktop/app/main/services/capabilities/tools/mcp-users/	Command-line dependency detection and auto-installation
McpRouter.ts	desktop/app/main/services/routers/	IPC routing registration, parameter validation
McpToolAdapter.ts	desktop/app/main/services/agent-core/engine/tinyelf/tools/	Adapter from MCPTool to ITool
McpProcessTracker.ts	desktop/app/main/services/agent-core/engine/tinyelf/tools/	Child process PID tracking and cleanup
mcp.worker.ts	desktop/app/main/workers/	Worker thread, CLI bridging
mcp-types.ts	desktop/app/shared/contracts/	Shared type definitions
mcp-presets.ts	desktop/app/shared/	Official MCP server presets
mcp-detector.ts	desktop/app/main/lib/utils/	MCP configuration detection utility
McpServersPage.tsx	renderer/src/pages/	MCP server management page
McpServerForm.tsx	renderer/src/features/settings/components/tabs/tools-tab/	Add/edit form
McpManageDialog.tsx	renderer/src/features/marketplace/components/mcp/	Agent association management
useMcpMode.ts	renderer/src/features/marketplace/hooks/mcp/	MCP mode and tool selection Hook
useMcpManagement.ts	renderer/src/features/settings/components/tabs/tools-tab/hooks/	CRUD management Hook

IPC Channels

All MCP-related IPC channels are registered via McpRouter using secureHandle for authentication:

Channel	Direction	Parameters	Return	Description
mcp:list	R→M	None	McpServerRecord[]	List all servers
mcp:add	R→M	McpServerInput	McpActionResult	Add server
mcp:addJson	R→M	McpServerJsonInput	McpActionResult	Batch add from JSON
mcp:remove	R→M	McpServerRemoveInput	McpActionResult	Remove server
mcp:update	R→M	{ id, updates }	McpActionResult	Update server config
mcp:test	R→M	McpServerRemoveInput	McpTestResult	Test connection
mcp:discover	R→M	McpServerRemoveInput	McpDiscoverResult	Discover tools/resources/prompts
mcp:list-server-tools	R→M	{ serverId }	MCPTool[]	List single server tools
mcp:list-all-tools	R→M	None	MCPTool[]	List all active server tools
mcp:call-tool	R→M	{ serverId, toolName, args, callId }	MCPCallToolResponse	Call tool
mcp:check-dependency	R→M	{ command }	DependencyCheckResult	Check dependency
mcp:install-dependency	R→M	{ command }	DependencyInstallResult	Install dependency

Core Types

type McpServerTransport = 'stdio' | 'http' | 'sse';
type McpServerScope = 'user' | 'local';
type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error';
type McpMode = 'disabled' | 'auto' | 'manual';

interface McpServerRecord {
  id: string;
  name: string;
  scope: McpServerScope;
  type: McpServerTransport;
  config: McpServerConfig;
  isActive?: boolean;
  isTrusted?: boolean;
  disabledTools?: string[];
  installSource?: 'builtin' | 'manual' | 'protocol' | 'unknown';
  createdAt?: number;
  updatedAt?: number;
}

interface MCPTool {
  id: string;           // mcp__serverName__toolName
  serverId: string;
  serverName: string;
  name: string;
  description?: string;
  inputSchema: Record<string, any>;
  type: 'mcp';
}

Inter-Module Dependencies

graph LR
    McpRouter --> McpService
    McpRouter --> DependencyCheckService
    McpService --> ConfigStore["Electron Store<br/>(mcp-config)"]
    McpService --> MCP_SDK["@modelcontextprotocol/sdk"]
    ToolsLoader --> McpService
    McpToolAdapter --> McpService
    CompletionService["CompletionService"] --> ToolsLoader
    TinyElfEngine --> McpToolAdapter
    TinyElfEngine --> DirectMcpToolAdapter

Data Flow

Tool Loading Flow

User initiates chat
    ↓
CompletionService calls setupMcpTools()
    ↓
fetchMcpTools() determines which servers to load based on MCP mode
    ↓ (auto: all active servers / manual: selected servers)
McpService.listServerTools() / listAllActiveServerTools()
    ↓ (check cache → hit: return / miss: initClient + listTools)
ToolsLoader converts to target format (OpenAI / Anthropic / Gemini)
    ↓
Tool definitions injected into LLM request

Tool Call Flow

LLM returns tool_call (name = mcp__server__tool)
    ↓
Parse server ID and tool name
    ↓
McpService.callTool(serverId, toolName, args, callId)
    ↓
initClient() ensures connection → client.callTool()
    ↓
Return MCPCallToolResponse (isError, content[])
    ↓
Result passed back to LLM for continued conversation

Related Documentation

• Connection Pool Management — McpService connection lifecycle details
• Tool Format Adapters — ToolsLoader and McpToolAdapter details
• Worker Architecture — mcp.worker.ts CLI bridging architecture
• How to Extend — Add new transport types and custom MCP servers