Welcome to AionUi's MCP (Model Context Protocol) configuration guide! This tutorial will provide detailed instructions on how to configure and manage MCP services in AionUi, helping you easily extend your AI assistant's capabilities.

English | 简体中文

MCP (Model Context Protocol) is an open standard that allows AI assistants to communicate securely and structurally with external tools and services. In AionUi, MCP enables you to:

• Extend AI functionality: Connect to various external tools and services
• Unified management: Manage all MCP services in one interface
• Simplify configuration: Support multiple addition methods, reducing configuration difficulty
• Real-time monitoring: Automatically test connection status to ensure service availability

AI Assistant ←→ MCP Protocol ←→ External Tools/Services

MCP acts as a middleware layer, allowing AI assistants to:

1. Discover tools: Automatically identify available tools and functions
2. Call services: Securely execute external operations
3. Get results: Receive and process data returned by services

AionUi currently supports the following MCP transport methods:

1. stdio: Standard input/output (most common)
2. sse: Server-sent events
3. http: HTTP requests
4. streamable-http: Streamable HTTP

Before starting MCP configuration, ensure:

• ✅ AionUi is properly installed and running
• ✅ At least one AI model is configured (Gemini, OpenAI, etc.)
• ✅ Basic understanding of JSON configuration format (optional)

1. Open AionUi
2. Enter Settings Page
   • Click the "Settings" icon in the left sidebar
3. Select Tools Settings
   • Choose "Tools Settings" in the settings page
4. Find MCP Management
   • Locate the "MCP Management" section in tools settings

This is the most flexible configuration method, suitable for experienced users:

The JSON configuration format for MCP services is as follows:

{
  "mcpServers": {
    "service-name": {
      "description": "Service description",
      "command": "command",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR_NAME": "env_var_value"
      }
    }
  }
}

1. Click Add Button

   • Click "Add MCP Service" button in MCP management interface
   • Select "Add via JSON"

2. Input Configuration

   • Paste JSON configuration in the popup dialog
   • Click "Confirm" button

3. Automatic Testing

   • AionUi will automatically test the connection
   • Successfully connected services will show green checkmark

If you have already configured MCP in CLI tools, you can use the one-click import feature:

1. Click Add Button

   • Click "Add MCP Service" button in MCP management interface
   • Select "Import from CLI"

2. Choose CLI

   • Select the CLI tool with configured MCP from the dropdown
   • Supported agents: Built-in Agent, Claude Code, Qwen Code, etc.

1. Click Import Button

   • After selecting CLI, click "Import from CLI" button
   • AionUi will automatically read the CLI's MCP configuration

2. Confirm Import

   • Review the imported service list
   • Click "Save" to complete the import

In the MCP management interface, each service displays:

• Service Name: MCP service identifier
• Connection Status:
  • ✅ Connected: Service running normally
  • ❌ Connection Failed: Service unavailable
  • 🔄 Testing: Testing connection
  • ⚪ Disconnected: Service not started
• Tool List: Click to expand and view available tools

1. Toggle Switch

   • Click the switch button on the right side of the service
   • After enabling, it will automatically sync to all CLI tools

2. View Sync Status

   • After successful enabling, CLI icons will appear next to the service name
   • Indicates the service has been synced to corresponding CLI tools

1. Manual Test

   • Click the refresh button on the right side of the service
   • Re-test the service connection status

2. View Results

   • Status icon will be updated after testing
   • Error information will be displayed if failed

1. Enter Edit Mode

   • Click the edit button on the right side of the service
   • Modify service configuration

2. Save Changes

   • Click save after modifications
   • System will automatically re-test the connection

1. Confirm Deletion

   • Click the delete button on the right side of the service
   • Click "Confirm" in the confirmation dialog

2. Clean Sync

   • After deletion, it will automatically remove from all CLI tools
   • Ensures configuration consistency

After configuring filesystem MCP service, you can:

User: Help me organize the files on my desktop
AI: I'll help you organize your desktop files. Let me first check what files are on your desktop...

[Calling filesystem MCP]
- Scan desktop directory
- Categorize by file type
- Create organized folder structure
- Move files to corresponding folders

Organization complete! I've categorized and organized your desktop files by type.

After configuring Chrome DevTools MCP, you can:

User: Help me open GitHub and search for AionUi project
AI: I'll help you open GitHub and search for the AionUi project.

[Calling chrome-devtools MCP]
- Open Chrome browser
- Navigate to GitHub.com
- Enter "AionUi" in search box
- Execute search operation

Search complete! I've opened GitHub and searched for the AionUi project for you.

After configuring Git MCP service, you can:

User: Help me check the commit history of the current project
AI: I'll help you check the project's commit history.

[Calling git MCP]
- Connect to Git repository
- Get commit history records
- Format and output commit information

Commit History:
commit abc123 - Fix login functionality (2024-01-15)
commit def456 - Add user management module (2024-01-14)
commit ghi789 - Initialize project (2024-01-13)

After configuring Memory MCP service, you can:

User: Help me remember this important information: project deadline is next Friday
AI: I'll help you remember this important information.

[Calling memory MCP]
- Store important information in memory
- Set reminder tags
- Confirm save success

Information saved! I've remembered "project deadline is next Friday" as important information.

Problem: MCP service shows red X, cannot connect

Possible Causes:

• Incorrect command path
• Dependencies not installed
• Network connection issues
• Insufficient permissions

Solutions:

1. Check Command: Ensure command and args configuration is correct
2. Install Dependencies: Run npm install -g package-name to install required packages
3. Check Network: Ensure network connection is normal
4. Permission Check: Ensure sufficient system permissions

Problem: Service connects successfully, but tool list is empty

Possible Causes:

• MCP service doesn't properly implement tool interface
• Service version incompatibility
• Missing configuration parameters

Solutions:

1. Check Service: Ensure MCP service implementation is correct
2. Update Version: Use the latest version of the service
3. Complete Configuration: Add necessary environment variables

Problem: Service works normally in AionUi, but CLI tools cannot use it

Possible Causes:

• CLI tool version is too old
• Configuration format incompatibility
• CLI tool not properly installed

Solutions:

1. Update CLI: Upgrade to the latest version
2. Re-sync: Disable and re-enable the service
3. Check Installation: Ensure CLI tool is properly installed

• MCP Official Specification - Official MCP protocol documentation
• AionUi GitHub - AionUi project homepage
• MCP Server List - Official MCP servers

• GitHub Discussions - Community discussions and feedback
• Issue Reports - Report bugs and feature requests
• Release Notes - View latest versions and updates

• Quick Start Guide - AionUi basic configuration
• LLM Configuration - AI model configuration tutorial
• Multi-Agent Mode Setup - CLI tool integration tutorial
• FAQ - Q&A and troubleshooting

Start your MCP journey and make your AI assistant more powerful! 🚀