MaiAgent MCP
Use MaiAgent MCP to let Claude, Cursor, and other external AI tools directly operate the MaiAgent platform — connection setup, authentication, and usage guide
1. What Is MaiAgent MCP?
MaiAgent MCP is the official remote MCP (Model Context Protocol) service provided by MaiAgent. After adding it to AI tools that support MCP — such as Claude Code, Claude Desktop, or Cursor — you can operate the MaiAgent platform directly using natural language. For example:
"Create a customer service AI Assistant using the Claude Sonnet model"
"List all Knowledge Bases in my Organization and upload this FAQ to the product Knowledge Base"
"Retrieve yesterday's Conversation records and summarize the most frequently asked questions"
Service Endpoint
https://mcp.maiagent.ai/mcp
Transport
Streamable HTTP (remote connection, no local installation required)
Authentication
MaiAgent API Key (HTTP Header)
Coverage
Full MaiAgent platform API: AI Assistants, Knowledge Bases, Conversations, tools, Organization management, and over 300 Endpoints
Available Tools
Once connected, your AI tool will have access to the following 6 tools. The AI automatically combines them (first searching for APIs, then checking specifications, and finally executing), so you don't need to remember any API details:
debug_auth
Check whether the authentication status is correct
list_api_categories
List all API categories
search_apis
Search API Endpoints by category or keyword
get_api_details
Retrieve the full specification of a specific API (Parameters, Request body, Response format)
call_api
Execute an actual API call
refresh_schema
Force reload the API list (use when a newly released API cannot be found; normally auto-updates every 5 minutes)
2. Prerequisites
Before you begin, you only need to prepare one API Key.
An API Key is bound to the Organization you are in when the Key is created. All MCP operations will apply to that Organization. If you belong to multiple Organizations, switch to the target Organization using the top-left selector in the Admin Console before creating the Key. Each member can have only one active Key per Organization.
Get an API Key
Log in to the MaiAgent Admin Console, click the avatar in the top-right corner → Profile → switch to the API Key tab → click Create New Key, and copy the generated API Key.
The API Key is displayed only once after creation. Copy and store it securely immediately. An API Key is equivalent to your login credentials — do not share it with others or commit it to version control (git).
3. Connection Setup
Choose the setup method that corresponds to the AI tool you are using. In the examples below, replace <YOUR_API_KEY> with the API Key you obtained in the prerequisites.
Run the following in your terminal:
-s user makes it available across all projects. To use it only in the current project, change to -s project (the configuration will be written to .mcp.json in the project root).
You can also manually edit .mcp.json directly:
When using -s project, Claude Code will ask whether to trust the project's MCP server on first launch — select agree. If the directory containing .mcp.json is a git project, add .mcp.json to .gitignore to prevent the API Key from being committed.
Edit the Claude Desktop configuration file (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json) and add:
Save and restart Claude Desktop.
Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json within your project, and add:
After saving, go to Cursor Settings → MCP and confirm that maiagent shows as connected.
Any MCP client that supports Streamable HTTP remote connections can be used. Key configuration settings:
Server URL
https://mcp.maiagent.ai/mcp
Transport
Streamable HTTP
Header: Authorization
Api-Key <YOUR_API_KEY>
4. Verify Connection
After completing the setup, ask the AI in your AI tool to call the debug_auth tool (for example, type "Call the maiagent debug_auth tool to check the connection"). You should see:
If has_auth_header is true, the connection and authentication are successful (organization_id showing null is normal — the target Organization is determined by the API Key itself).
5. Getting Started
Once connected, simply give instructions in natural language. The AI will automatically follow the search_apis → get_api_details → call_api workflow to find and execute the corresponding API. Here are some practical command examples:
Query: "List all my AI Assistants", "Who are the members in this Organization?"
Create: "Create an AI Assistant named 'Product Support' with the role instructions..."
Knowledge Base: "Create a new Knowledge Base and list the current files"
Operations: "Check the recent Conversations for the 'Product Support' Assistant and summarize the common questions"
Operations performed through MCP have the same effect as manual operations in the Admin Console (with permissions equivalent to your account). Before performing deletions, modifications, or other changes, ask the AI to explain what it is about to execute.
6. Troubleshooting
Connection failed, 401 Response
The API Key is incorrect, has been deleted, or the Authorization header is missing. Verify the format is Api-Key <YOUR_API_KEY> (with a space between Api-Key and the Key).
Operating on the wrong Organization (expected Assistants/Knowledge Bases not found)
The API Key is bound to the Organization you were in when the Key was created. Switch to the correct Organization, create a new Key, and update the configuration file.
Tool list is empty
The connection was not established successfully. Restart your AI tool. In Claude Code, use the /mcp command to check the connection status.
Claude Code shows Pending approval
Project-level (-s project) MCP requires trust approval before connecting. Launch interactive Claude Code and follow the prompt to approve.
Permission error when executing an API
call_api executes under your identity and can only operate on resources your account has permission to access. Verify your role permissions in that Organization.
Last updated
Was this helpful?