# How to Integrate AionUi with MCP Servers: Complete Developer Guide

> Learn how to integrate AionUi with MCP servers using this developer guide. Explore its layered IPC architecture and transport protocols like stdio, HTTP, SSE, and Streamable-HTTP.

- Repository: [OfficeAI/AionUi](https://github.com/iofficeai/aionui)
- Tags: how-to-guide
- Published: 2026-02-15

---

**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`](https://github.com/iOfficeAI/AionUi/blob/main/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](https://github.com/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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/McpProtocol.ts) provides common functionality, while concrete agents like `GeminiMcpAgent` in [`src/process/services/mcpServices/agents/GeminiMcpAgent.ts`](https://github.com/iOfficeAI/AionUi/blob/main/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.

```typescript
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`](https://github.com/iOfficeAI/AionUi/blob/main/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.

```typescript
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`](https://github.com/iOfficeAI/AionUi/blob/main/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.

```typescript
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`](https://github.com/iOfficeAI/AionUi/blob/main/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.

```typescript
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`](https://github.com/iOfficeAI/AionUi/blob/main/src/process/services/mcpServices/McpOAuthService.ts) implements the token storage and flow management, while [`src/renderer/hooks/mcp/useMcpOAuth.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/renderer/hooks/mcp/useMcpOAuth.ts) provides the UI integration.

## Key Implementation Files

| Role | File | Description |
|------|------|-------------|
| IPC Definition | [`src/common/ipcBridge.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/common/ipcBridge.ts) | Exposes `mcpService` methods to the renderer process |
| Bridge Implementation | [`src/process/bridge/mcpBridge.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/process/bridge/mcpBridge.ts) | Registers providers for MCP operations and forwards to service layer |
| Service Orchestration | [`src/process/services/mcpServices/McpService.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/process/services/mcpServices/McpService.ts) | Manages agent registry and high-level MCP operations |
| Protocol Definition | [`src/process/services/mcpServices/McpProtocol.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/process/services/mcpServices/McpProtocol.ts) | Defines `IMcpProtocol` interface and `AbstractMcpAgent` base class |
| OAuth Management | [`src/process/services/mcpServices/McpOAuthService.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/process/services/mcpServices/McpOAuthService.ts) | Handles token storage, login flows, and authentication status |
| Agent Implementation | [`src/process/services/mcpServices/agents/GeminiMcpAgent.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/process/services/mcpServices/agents/GeminiMcpAgent.ts) | Example concrete agent implementing transport-specific logic |
| UI Operations Hook | [`src/renderer/hooks/mcp/useMcpOperations.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/renderer/hooks/mcp/useMcpOperations.ts) | React hook for sync and remove operations |
| Connection Hook | [`src/renderer/hooks/mcp/useMcpConnection.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/renderer/hooks/mcp/useMcpConnection.ts) | React hook for testing MCP connections |
| OAuth Hook | [`src/renderer/hooks/mcp/useMcpOAuth.ts`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/McpProtocol.ts) return a result with `needsAuth: true` and the `authMethod`. The UI can then invoke `mcpService.loginMcpOAuth`, which delegates to [`McpOAuthService.ts`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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`](https://github.com/iOfficeAI/AionUi/blob/main/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.