MaiAgent MCP

透過 MaiAgent MCP，讓 Claude、Cursor 等外部 AI 工具直接操作 MaiAgent 平台 — 連線設定、認證與使用教學

一、MaiAgent MCP 是什麼？

MaiAgent MCP 是 MaiAgent 官方提供的遠端 MCP（Model Context Protocol）服務。將它加入 Claude Code、Claude Desktop、Cursor 等支援 MCP 的 AI 工具後，您就可以直接用自然語言操作 MaiAgent 平台，例如：

「幫我建立一個客服 AI 助理，使用 Claude Sonnet 模型」
「列出我組織裡所有的知識庫，並把這份 FAQ 上傳到產品知識庫」
「查詢昨天的對話紀錄，整理出使用者最常問的問題」

項目

說明

服務端點

https://mcp.maiagent.ai/mcp

傳輸方式

Streamable HTTP（遠端連線，無需在本機安裝任何程式）

認證方式

MaiAgent API Key（HTTP Header）

涵蓋範圍

MaiAgent 平台完整 API：AI 助理、知識庫、對話、工具、組織管理等 300 多個端點

提供的工具

連線成功後，您的 AI 工具會取得以下 6 個工具。AI 會自動組合使用它們（先搜尋 API、再查規格、最後執行），您不需要記住任何 API 細節：

工具

用途

debug_auth

檢查認證狀態是否正確

list_api_categories

列出所有 API 分類

search_apis

依分類或關鍵字搜尋 API 端點

get_api_details

取得特定 API 的完整規格（參數、請求體、回應格式）

call_api

實際執行 API 呼叫

refresh_schema

強制重新載入 API 清單（找不到剛上線的新 API 時使用；平常每 5 分鐘會自動更新）

方向不要搞混了：本頁教的是「把 MaiAgent 接進外部 AI 工具」。如果您想做的是相反方向 —— 在 MaiAgent 的 AI 助理裡掛上其他 MCP 工具，請參考建立 MCP 工具。

二、前置準備

開始前，您只需要準備一把 API Key。

API Key 會綁定「建立金鑰當下所在的組織」，MCP 的所有操作都會作用在這個組織上。若您隸屬多個組織，請先在後台左上角切換到要操作的組織，再建立金鑰。每位成員在同一個組織內只能有一把有效金鑰。

取得 API Key

登入 MaiAgent 管理後台，點擊右上角頭像 → 個人資料 → 切換到 API 金鑰頁籤 → 點擊建立新金鑰，複製產生的 API Key。

API Key 建立後只會顯示一次，請立即複製並妥善保存。API Key 等同您的登入身分，請勿分享給他人，也不要提交到版本控制（git）中。

三、連線設定

依您使用的 AI 工具選擇對應的設定方式。以下範例中，請將 <YOUR_API_KEY> 替換成您在前置準備取得的 API Key。

在終端機執行：

claude mcp add --transport http maiagent https://mcp.maiagent.ai/mcp \
  -s user \
  --header "Authorization: Api-Key <YOUR_API_KEY>"

-s user 代表在所有專案都能使用；若只想在目前專案使用，改成 -s project（設定會寫入專案根目錄的 .mcp.json）。

也可以直接手動編輯 .mcp.json：

{
  "mcpServers": {
    "maiagent": {
      "type": "http",
      "url": "https://mcp.maiagent.ai/mcp",
      "headers": {
        "Authorization": "Api-Key <YOUR_API_KEY>"
      }
    }
  }
}

使用 -s project 時，Claude Code 第一次啟動會詢問是否信任此專案的 MCP server，請選擇同意。若 .mcp.json 所在目錄是 git 專案，請將 .mcp.json 加入 .gitignore，避免 API Key 被提交。

編輯 Claude Desktop 設定檔（macOS：~/Library/Application Support/Claude/claude_desktop_config.json；Windows：%APPDATA%\Claude\claude_desktop_config.json），加入：

{
  "mcpServers": {
    "maiagent": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.maiagent.ai/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Api-Key <YOUR_API_KEY>"
      }
    }
  }
}

儲存後重新啟動 Claude Desktop。

此方式需要本機已安裝 Node.js。Authorization 的值透過 env 傳入，是為了避免設定檔中含空白字元的參數被錯誤切割。

編輯 ~/.cursor/mcp.json（全域）或專案下的 .cursor/mcp.json，加入：

{
  "mcpServers": {
    "maiagent": {
      "url": "https://mcp.maiagent.ai/mcp",
      "headers": {
        "Authorization": "Api-Key <YOUR_API_KEY>"
      }
    }
  }
}

儲存後到 Cursor Settings → MCP 確認 maiagent 顯示為已連線。

任何支援 Streamable HTTP 遠端連線的 MCP 客戶端都可以使用，設定要點：

設定項

值

Server URL

https://mcp.maiagent.ai/mcp

Transport

Streamable HTTP

Header：Authorization

Api-Key <YOUR_API_KEY>

四、驗證連線

設定完成後，在您的 AI 工具中請 AI 呼叫 debug_auth 工具（例如直接輸入「請呼叫 maiagent 的 debug_auth 工具檢查連線」），預期會看到：

{
  "has_auth_header": true,
  "auth_header_preview": "Api-Key xxxxxxxx...",
  "has_organization_id": false,
  "organization_id": null
}

has_auth_header 是 true 就代表連線與認證都成功了（organization_id 顯示 null 是正常的——要操作的組織由 API Key 本身決定）。

五、開始使用

連線成功後，直接用自然語言下指令即可。AI 會自動透過 search_apis → get_api_details → call_api 的流程找到並執行對應的 API。一些實用的指令範例：

查詢：「列出我的所有 AI 助理」、「這個組織有哪些成員？」
建立：「建立一個名為『產品客服』的 AI 助理，角色指令是……」
知識庫：「建立一個新知識庫，並列出目前有哪些檔案」
維運：「查一下『產品客服』助理最近的對話，幫我摘要常見問題」

透過 MCP 執行的操作與您在後台手動操作具有相同效力（權限等同您的帳號）。進行刪除、修改等變更前，建議先請 AI 說明它即將執行的操作內容。

六、疑難排解

症狀

可能原因與解法

連線失敗、回應 401

API Key 錯誤、已被刪除，或 Authorization header 沒帶到。請確認格式為 Api-Key <YOUR_API_KEY>（Api-Key 與金鑰之間有一個空格）。

操作到錯誤的組織（查不到預期的助理／知識庫）

API Key 綁定的是「建立金鑰當下所在的組織」。請切換到正確的組織後重新建立金鑰，並更新設定檔。

工具清單是空的

連線未成功建立，請重新啟動 AI 工具；Claude Code 可用 /mcp 指令檢查連線狀態。

Claude Code 顯示 Pending approval

專案層級（-s project）的 MCP 需要先信任才會連線，啟動互動式 Claude Code 依提示同意即可。

執行 API 時出現權限錯誤

call_api 使用您的身分執行，只能操作您帳號有權限的資源。請確認您在該組織的角色權限。

若您使用的是專屬部署（On-Premise）環境，MCP 服務端點會與雲端版不同，請聯絡您的 MaiAgent 服務窗口確認。

最後更新於 8 天前

這有幫助嗎？