# How to Configure MCP Servers in AionUi to Extend AI Agent Capabilities

> Learn to configure MCP servers in AionUi to boost AI agent functions. Follow our guide for seamless integration and enhanced capabilities with OAuth support.

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

---

**Configure MCP servers in AionUi by defining an `IMcpServer` object with transport settings, persisting it to the local database, and synchronizing it to agents via the `syncMcpToAgents` IPC method, with OAuth handling for HTTP/SSE transports.**

AionUi leverages the **Model Context Protocol (MCP)** to expand AI agent capabilities by connecting Claude, Gemini, CodeBuddy, and other agents to external tools and data sources. Configuring these servers involves creating structured definitions in the storage layer, propagating them through the IPC bridge, and managing authentication for remote endpoints. The architecture separates concerns between the SQLite persistence layer, the backend service orchestration, and the React-based renderer interface.

## MCP Configuration Architecture Overview

The configuration flow operates across three distinct layers, each handled by specific modules in the codebase:

- **Persistence Layer**: Stores server definitions as `IMcpServer` objects in the local Better SQLite database via [[`src/common/storage.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/common/storage.ts)](https://github.com/iOfficeAI/AionUi/blob/main/src/common/storage.ts)
- **Backend Services**: Manages server lifecycle, agent synchronization, and OAuth flows in [[`McpService.ts`](https://github.com/iOfficeAI/AionUi/blob/main/McpService.ts)](https://github.com/iOfficeAI/AionUi/blob/main/src/process/services/mcpServices/McpService.ts) and [[`McpOAuthService.ts`](https://github.com/iOfficeAI/AionUi/blob/main/McpOAuthService.ts)](https://github.com/iOfficeAI/AionUi/blob/main/src/process/services/mcpServices/McpOAuthService.ts)
- **IPC Bridge & UI**: Exposes type-safe methods to the renderer through [[`mcpBridge.ts`](https://github.com/iOfficeAI/AionUi/blob/main/mcpBridge.ts)](https://github.com/iOfficeAI/AionUi/blob/main/src/process/bridge/mcpBridge.ts) and consumes them via React hooks like `useMcpOperations`

## Defining the IMcpServer Configuration Object

An MCP server is defined as a plain object conforming to the `IMcpServer` interface. This structure captures connection parameters, transport protocols, and metadata required by the agents.

```typescript
// src/common/storage.ts
export interface IMcpServer {
  id: string;
  name: string;
  description?: string;
  enabled: boolean;               // Controls installation into agents
  transport: IMcpServerTransport; // stdio | http | sse | streamable_http
  tools?: IMcpTool[];             // Optional tool definitions
  status?: 'connected' | 'disconnected' | 'error' | 'testing';
  lastConnected?: number;
  createdAt: number;
  updatedAt: number;
  originalJson: string;           // Raw JSON for UI editing
}

```

### Transport Types and Schema

The `transport` field determines how the agent communicates with the server:

- **stdio**: Executes a local command with optional arguments
- **http**: Connects to a REST endpoint, often requiring OAuth
- **sse**: Uses Server-Sent Events for real-time streaming

Example transport configurations:

```typescript
// stdio transport
const stdioTransport = {
  type: 'stdio',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', '/path/to/dir']
};

// http transport with headers
const httpTransport = {
  type: 'http',
  url: 'https://api.example.com/mcp',
  headers: { 'Authorization': 'Bearer token123' }
};

```

## Syncing Configurations to AI Agents

Once a server definition exists in storage, you must synchronize it to the target agents using the IPC bridge. The [`syncMcpToAgents`](https://github.com/iOfficeAI/AionUi/blob/main/src/process/services/mcpServices/McpService.ts) method handles the distribution across different agent backends.

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

async function deployMcpServer(server, selectedAgents) {
  const response = await mcpService.syncMcpToAgents.invoke({
    mcpServers: [server],    // IMcpServer[] from storage
    agents: selectedAgents   // Agent config array
  });
  
  return response.success;
}

```

The backend service resolves the correct agent implementation using `getAgentForConfig`, which differentiates between forked and native Gemini instances. This logic ensures the MCP configuration is applied to the appropriate process type [\[source\]](https://github.com/iOfficeAI/AionUi/blob/main/src/process/services/mcpServices/McpService.ts#L88-L95).

## Validating Server Connectivity

Before deploying to production agents, test the connection using the `testMcpConnection` method. This verifies that the transport layer can establish a connection and that the server responds to MCP protocol handshakes.

```typescript
const result = await mcpService.testMcpConnection.invoke(server);

if (result.success) {
  console.log('Connection validated:', result.msg);
} else {
  console.error('Connection failed:', result.error);
}

```

The backend forwards this request to the first available agent capable of handling the transport type, returning a `McpConnectionTestResult` with detailed status information [\[source\]](https://github.com/iOfficeAI/AionUi/blob/main/src/process/services/mcpServices/McpService.ts#L73-L80).

## Authenticating HTTP and SSE Endpoints via OAuth

Remote HTTP and SSE servers frequently require OAuth authentication. AionUi encapsulates this flow within `McpOAuthService`, providing a complete authentication lifecycle.

### Checking Authentication Status

First, determine whether the server requires authentication and if valid credentials exist:

```typescript
const status = await mcpService.checkOAuthStatus.invoke(server);

if (status.data.needsLogin) {
  // Prompt user to authenticate
}

```

The `checkOAuthStatus` method inspects the HTTP response for `WWW-Authenticate` headers and checks the local token store for existing credentials [\[source\]](https://github.com/iOfficeAI/AionUi/blob/main/src/process/services/mcpServices/McpOAuthService.ts#L46-L92).

### Initiating the OAuth Flow

To authenticate, invoke the login method which handles the interactive OAuth handshake:

```typescript
const loginResult = await mcpService.loginMcpOAuth.invoke({
  server,
  config: { enabled: true }
});

if (loginResult.success) {
  // Token stored and server ready
}

```

The `login` method constructs an `MCPOAuthProvider` and manages the browser-based authentication flow, emitting progress events to the UI [\[source\]](https://github.com/iOfficeAI/AionUi/blob/main/src/process/services/mcpServices/McpOAuthService.ts#L19-L48).

### Revoking Access

To remove authentication tokens and disconnect the server:

```typescript
await mcpService.logoutMcpOAuth.invoke(server.name);

```

This clears the stored token from the secure storage [\[source\]](https://github.com/iOfficeAI/AionUi/blob/main/src/process/services/mcpServices/McpOAuthService.ts#L74-L80).

## Removing MCP Servers from Agents

When deprecating a server, remove it from all target agents to prevent stale connections:

```typescript
await mcpService.removeMcpFromAgents.invoke({
  mcpServerName: server.name,
  agents: selectedAgents
});

```

The backend iterates through the specified agents and invokes `removeMcpServer` on each, respecting the agent-specific implementation details (fork vs. native) through the same `getAgentForConfig` resolution logic [\[source\]](https://github.com/iOfficeAI/AionUi/blob/main/src/process/services/mcpServices/McpService.ts#L40-L53).

## Summary

- **Define** MCP servers using the `IMcpServer` interface with appropriate transport configurations (stdio, HTTP, or SSE)
- **Persist** configurations to the SQLite database via the storage layer
- **Synchronize** enabled servers to agents using `syncMcpToAgents`, which handles agent-specific implementation details
- **Test** connections before deployment using `testMcpConnection` to verify protocol compatibility
- **Authenticate** HTTP/SSE endpoints through the OAuth service using `checkOAuthStatus`, `loginMcpOAuth`, and `logoutMcpOAuth`
- **Remove** obsolete servers via `removeMcpFromAgents` to maintain clean agent environments

## Frequently Asked Questions

### What transport types does AionUi support for MCP servers?

AionUi supports **stdio** for local command execution, **HTTP** for RESTful endpoints, and **SSE** (Server-Sent Events) for streaming connections. The transport type is specified in the `IMcpServer.transport` field and determines which connection logic the agent uses when initializing the MCP client.

### How does AionUi handle OAuth authentication for MCP servers?

The [`McpOAuthService`](https://github.com/iOfficeAI/AionUi/blob/main/src/process/services/mcpServices/McpOAuthService.ts) manages OAuth flows through three IPC methods: `checkOAuthStatus` inspects the server for authentication requirements, `loginMcpOAuth` initiates the interactive browser flow, and `logoutMcpOAuth` revokes stored tokens. The service stores tokens securely and injects them into HTTP headers for subsequent requests.

### Where are MCP server configurations stored in AionUi?

Configurations persist in a local Better SQLite database defined in [[`src/common/storage.ts`](https://github.com/iOfficeAI/AionUi/blob/main/src/common/storage.ts)](https://github.com/iOfficeAI/AionUi/blob/main/src/common/storage.ts). The `IMcpServer` interface defines the schema, including metadata, transport details, and the `originalJson` field that preserves the raw configuration for UI editing.

### How do I troubleshoot a failing MCP server connection?

First, verify the transport configuration and network accessibility. Then use the `testMcpConnection` method to validate the connection without modifying agent state. For HTTP/SSE servers, check `checkOAuthStatus` to ensure valid authentication tokens exist. Review the agent-specific logs, as the backend service forwards connection attempts to the first available agent capable of handling the specified transport protocol.