How to Integrate AionUi with MCP Servers: Complete Developer Guide

AionUi integrates with MCP (Model Context Protocol) servers through a layered IPC architecture where the renderer process invokes methods exposed by ipcBridge.mcpService, which routes through mcpBridge.ts to agent-specific implementations that handle transport protocols including stdio, HTTP, SSE, and Streamable-HTTP.

Integrating AionUi with MCP servers enables your application to extend AI agent capabilities through standardized tool protocols. This guide walks through the complete architecture and implementation patterns found in the iOfficeAI/AionUi repository, showing exactly how to connect, test, and authenticate with MCP servers across multiple AI backends including Claude, Gemini, and Qwen.

Understanding the MCP Integration Architecture

Renderer-to-Main Process Bridge

The integration begins in the renderer process through mcpService exposed via ipcBridge in src/common/ipcBridge.ts. This exposes typed IPC methods that React UI components call to perform MCP operations. The bridge implementation in src/process/bridge/mcpBridge.ts registers providers for each MCP operation—including get configs, test connection, sync, remove, and OAuth helpers—and forwards requests to the service layer.

Service Layer and Agent Registry

The central orchestration happens in src/process/services/mcpServices/McpService.ts, which maintains a map of agent-specific MCP agents (Claude, Gemini, Qwen, Aionui). Each agent implements the generic IMcpProtocol interface defined in src/process/services/mcpServices/McpProtocol.ts. When a request arrives, McpService uses getAgentForConfig to select the appropriate agent implementation—distinguishing between fork-Gemini and native Gemini variants—and delegates the operation.

Transport Protocol Abstraction

Each agent implementation handles transport-specific logic. The AbstractMcpAgent base class in McpProtocol.ts provides common functionality, while concrete agents like GeminiMcpAgent in src/process/services/mcpServices/agents/GeminiMcpAgent.ts implement transport-specific connection logic for stdio, HTTP, SSE (Server-Sent Events), and Streamable-HTTP protocols.

Step-by-Step Integration Workflow

1. Discover and List MCP Servers

To populate the UI with available MCP configurations, use the getAgentMcpConfigs method. This retrieves MCP server configurations for all available AI agents.

import { mcpService } from '@/common/ipcBridge';

async function discoverServers() {
  // Get available agents first
  const agentsResp = await window.ipcRenderer.invoke('acpConversation.getAvailableAgents');
  if (!agentsResp.success) throw new Error('Failed to load agents');

  // Retrieve MCP configs for these agents
  const mcpResp = await mcpService.getAgentMcpConfigs.invoke(agentsResp.data);
  if (mcpResp.success && mcpResp.data) {
    const allServers = mcpResp.data.flatMap(r => r.servers);
    return allServers;
  }
}

Relevant source: src/renderer/hooks/mcp/useMcpAgentStatus.ts implements this discovery pattern.

2. Test MCP Server Connections

Before syncing, validate server connectivity using testMcpConnection. This performs transport-specific validation including OAuth requirement detection.

import { mcpService } from '@/common/ipcBridge';

async function testServer(server) {
  const resp = await mcpService.testMcpConnection.invoke(server);
  if (!resp.success) {
    console.error('Connection test failed:', resp.msg);
    return;
  }

  if (resp.data?.needsAuth) {
    console.log('Server requires auth via', resp.data.authMethod);
    // Trigger OAuth flow
  } else {
    console.log('Server reachable, tools:', resp.data?.tools);
  }
}

Relevant source: The implementation resides in AbstractMcpAgent.testMcpConnection with transport helpers in src/process/services/mcpServices/McpProtocol.ts.

3. Sync Servers to AI Agents

Deploy MCP server configurations to specific AI agents using syncMcpToAgents. This installs the servers on each selected agent's backend.

import { mcpService, acpConversation } from '@/common/ipcBridge';

export async function syncServer(server) {
  // Get available agents
  const agentsResp = await acpConversation.getAvailableAgents.invoke();
  if (!agentsResp.success) throw new Error('No agents available');

  // Sync to selected agents
  const syncResp = await mcpService.syncMcpToAgents.invoke({
    mcpServers: [server],
    agents: agentsResp.data,
  });

  if (!syncResp.success) {
    console.error('Sync failed:', syncResp.msg);
  } else {
    console.log('Sync results per agent:', syncResp.data?.results);
  }
}

Relevant source: src/renderer/hooks/mcp/useMcpOperations.ts contains this exact pattern with status messaging.

4. Handle OAuth Authentication

For servers requiring authentication, use the OAuth service methods to manage tokens and login flows.

import { mcpService } from '@/common/ipcBridge';

async function handleOAuth(server) {
  // Check current auth status
  const status = await mcpService.checkOAuthStatus.invoke(server);
  if (!status.success || !status.data?.needsLogin) return;

  // Trigger login – the provider opens a browser window internally
  const loginResp = await mcpService.loginMcpOAuth.invoke({ server });
  
  if (loginResp.success) {
    console.log('OAuth login successful');
  } else {
    console.error('OAuth login failed:', loginResp.msg);
  }
}

Relevant source: src/process/services/mcpServices/McpOAuthService.ts implements the token storage and flow management, while src/renderer/hooks/mcp/useMcpOAuth.ts provides the UI integration.

Key Implementation Files

Role	File	Description
IPC Definition	src/common/ipcBridge.ts	Exposes mcpService methods to the renderer process
Bridge Implementation	src/process/bridge/mcpBridge.ts	Registers providers for MCP operations and forwards to service layer
Service Orchestration	src/process/services/mcpServices/McpService.ts	Manages agent registry and high-level MCP operations
Protocol Definition	src/process/services/mcpServices/McpProtocol.ts	Defines IMcpProtocol interface and AbstractMcpAgent base class
OAuth Management	src/process/services/mcpServices/McpOAuthService.ts	Handles token storage, login flows, and authentication status
Agent Implementation	src/process/services/mcpServices/agents/GeminiMcpAgent.ts	Example concrete agent implementing transport-specific logic
UI Operations Hook	src/renderer/hooks/mcp/useMcpOperations.ts	React hook for sync and remove operations
Connection Hook	src/renderer/hooks/mcp/useMcpConnection.ts	React hook for testing MCP connections
OAuth Hook	src/renderer/hooks/mcp/useMcpOAuth.ts	React hook for OAuth flow UI integration

Summary

• AionUi connects to MCP servers through a layered IPC architecture spanning renderer, bridge, and service layers.
• The mcpService API in src/common/ipcBridge.ts exposes methods for discovery, testing, syncing, and OAuth management.
• Agent-specific implementations in src/process/services/mcpServices/agents/ handle transport protocols (stdio, HTTP, SSE, Streamable-HTTP) for different AI backends like Claude, Gemini, and Qwen.
• OAuth authentication is managed through McpOAuthService.ts with automatic token storage and flow handling via @office-ai/aioncli-core.
• UI integration relies on React hooks (useMcpOperations, useMcpConnection, useMcpOAuth) that invoke the IPC bridge for type-safe communication between the renderer and main processes.

Frequently Asked Questions

What transport protocols does AionUi support for MCP servers?

AionUi supports multiple transport protocols through its agent architecture. The AbstractMcpAgent base class in src/process/services/mcpServices/McpProtocol.ts implements transport-specific testers for stdio, HTTP, SSE (Server-Sent Events), and Streamable-HTTP. Each concrete agent (such as GeminiMcpAgent or ClaudeMcpAgent) selects the appropriate transport based on the server configuration and handles the low-level connection logic accordingly.

How does AionUi handle authentication for MCP servers requiring OAuth?

When a connection test returns a 401 response, the testHttpConnection or testSseConnection methods in McpProtocol.ts return a result with needsAuth: true and the authMethod. The UI can then invoke mcpService.loginMcpOAuth, which delegates to McpOAuthService.ts. This service uses @office-ai/aioncli-core's MCPOAuthProvider and MCPOAuthTokenStorage to manage browser-based login flows and persistent token storage, automatically attaching tokens to subsequent connections.

Can I add support for a new AI agent backend in AionUi's MCP integration?

Yes. Adding a new backend requires implementing the IMcpProtocol interface defined in src/process/services/mcpServices/McpProtocol.ts. You create a new agent class (e.g., NewAgentMcpAgent) extending AbstractMcpAgent and implement methods like installMcpServers, removeMcpServers, and testMcpConnection. Finally, register the new agent in the agents map within src/process/services/mcpServices/McpService.ts to make it available for MCP operations across the application.

What is the difference between syncMcpToAgents and testMcpConnection in the AionUi API?

testMcpConnection performs a validation check against a single MCP server without modifying agent configurations—it executes transport-specific tests (like JSON-RPC initialize and tools/list calls) to verify connectivity and detect OAuth requirements. In contrast, syncMcpToAgents actually deploys MCP server configurations to selected AI agents by calling installMcpServers on each target agent, persisting the configuration and establishing the server connection for actual use in AI conversations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}