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

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)
• Backend Services: Manages server lifecycle, agent synchronization, and OAuth flows in [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/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/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.

// 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:

// 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 method handles the distribution across different agent backends.

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].

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.

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].

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:

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].

Initiating the OAuth Flow

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

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].

Revoking Access

To remove authentication tokens and disconnect the server:

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

This clears the stored token from the secure storage [source].

Removing MCP Servers from Agents

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

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].

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 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). 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.

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