MaiAgent MCP：讓外部 AI 工具操作平台

讓 Claude、Cursor 等支援 MCP 的 AI 工具透過 MaiAgent MCP 操作平台：服務端點與提供的工具、API Key 與 OAuth 兩種連法、驗證與疑難排解

本頁寫給要讓 Claude Code、Claude Desktop、Cursor 等 AI 工具透過 MaiAgent MCP 操作平台的開發者：服務端點與提供的工具、API Key 與 OAuth 兩種連法的設定、連線驗證與疑難排解。MCP 本身的概念見 MCP（Model Context Protocol）。

一、MaiAgent MCP 是什麼？

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

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

項目

說明

服務端點

https://mcp.maiagent.ai/mcp

傳輸方式

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

認證方式

API Key（放在 HTTP 標頭），或 OAuth 2.1（成員在瀏覽器登入 MaiAgent 並同意授權）

涵蓋範圍

MaiAgent 平台完整 API：Agent、知識庫、對話、工具、組織管理等 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 分鐘會自動更新）

工具的輸入格式

工具

輸入欄位

說明

debug_auth、list_api_categories、refresh_schema

無

—

search_apis

category（string，選填）、search（string，選填）、limit（number，選填，預設 20）

search 可填多個詞，以空格分隔，每個詞都要命中；回傳符合的端點與 operation_id

get_api_details

operation_id（string，必填）

回傳該端點的路徑、方法、參數、請求與回應結構

call_api

operation_id（string，必填）、path_params（object，選填）、query_params（object，選填）、body（object，選填）

實際呼叫；三個物件都是「名稱→值」的平面物件

call_api 的規則：

operation_id 是 API 文件各端點標示的 operationId，例如 v1KnowledgeBasesFilesList。
path_params 的 key 對應路徑中的 {…} 名稱（例如 knowledgeBasePk），值會經 URL 編碼後代入；缺少路徑參數時呼叫失敗，不會送出。
query_params 直接成為查詢字串；body 以 JSON 送出，只有 POST／PUT／PATCH 需要。
認證沿用連線時的 API Key 或 OAuth 權杖，不需要在參數裡帶金鑰；權限等同該成員的角色。
回應超過 50,000 bytes 時會被截斷並標示，請用分頁參數或篩選縮小結果。
API 回傳的錯誤（400、403、404 等）會原樣帶回給 AI，內容格式見 API 共通規範：錯誤回應。

以「列出某個知識庫的 PDF 檔案」為例，AI 會依序呼叫：

// 1. search_apis
{"search": "knowledge base files", "limit": 5}

// 2. get_api_details
{"operation_id": "v1KnowledgeBasesFilesList"}

// 3. call_api
{
  "operation_id": "v1KnowledgeBasesFilesList",
  "path_params": {"knowledgeBasePk": "550e8400-e29b-41d4-a716-446655440000"},
  "query_params": {"fileType": "pdf", "pageSize": 20}
}

方向不要搞混了：本頁教的是「把 MaiAgent 接進外部 AI 工具」。如果您想做的是相反方向 —— 在 MaiAgent 的 Agent 裡掛上其他 MCP 工具，後台操作請參考使用者手冊的建立 MCP 工具，自家系統要做成 MCP Server 的規格見自架 MCP Server 接入規格。

二、前置準備

開始前，先決定用哪一種方式認證：

認證方式

適合誰

要準備什麼

API Key

個人或自動化腳本，所有支援自訂標頭的 MCP 客戶端都能用

一把 API Key，見下方取得 API Key

OAuth

讓多位成員用自己的帳號連線，不必把金鑰貼進設定檔

管理員先建立 OAuth 應用程式，見下方準備 OAuth 應用程式

兩種方式的操作權限都等同成員自己的角色權限。

API Key 會綁定「建立金鑰當下所在的組織」，MCP 的所有操作都會作用在這個組織上。若您隸屬多個組織，請先在後台左上角切換到要操作的組織，再建立金鑰。每位成員可以持有多把金鑰，管理方式見使用者手冊的 API Key 管理。

取得 API Key

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

詳細說明見使用者手冊的個人帳號設定：API 金鑰；由管理員代發金鑰的方式見 API Key 管理。

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

準備 OAuth 應用程式

用 OAuth 連線前，需要由具「OAuth 應用程式管理權限」的管理員在組織建立一個應用程式：

到組織設定 → 組織概覽 → 管理操作 → OAuth 應用程式，點選建立應用程式。
應用程式類型選 Public。
Redirect URIs 填 MCP 客戶端授權完成後導回的網址，必須和客戶端實際使用的網址完全相同，例如 Claude 網頁版的 https://claude.ai/api/mcp/auth_callback；Claude Code 見下方用 OAuth 連線。
建立後把 Client ID 提供給要連線的成員。

完整步驟見使用者手冊的 OAuth 應用程式。

透過 OAuth 連線時，操作的是應用程式所屬的組織。要操作另一個組織，請使用該組織建立的應用程式。
授權頁只提供 Email 與密碼登入。只用 SSO 登入、沒有登入密碼的成員無法完成授權，請改用 API Key，見只用 SSO 登入的成員。

三、連線設定

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

在終端機執行：

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>

用 OAuth 連線

用 OAuth 連線時，設定裡不要帶 Authorization 標頭。MCP 客戶端第一次連線時會收到 MaiAgent MCP 要求授權的回應，接著開啟瀏覽器讓您登入 MaiAgent；授權頁會顯示應用程式名稱、所屬組織與目前登入的帳號，確認後按「授權」即完成。之後客戶端會自動續期，不需要每次登入。

MaiAgent 不支援動態用戶端註冊，MCP 客戶端必須能填入預先建立的 Client ID。

在終端機執行（8765 可換成任一固定的連接埠）：

claude mcp add --transport http maiagent https://mcp.maiagent.ai/mcp \
  -s user \
  --client-id <CLIENT_ID> \
  --callback-port 8765

OAuth 應用程式的 Redirect URIs 要登記 http://localhost:8765/callback，連接埠必須和 --callback-port 相同。

設定完成後在 Claude Code 輸入 /mcp，選擇 maiagent 並依提示完成瀏覽器授權。

在 Claude 的連接器設定新增自訂連接器：網址填 https://mcp.maiagent.ai/mcp，在進階設定填入 OAuth Client ID，再依提示連線並完成授權。

OAuth 應用程式的 Redirect URIs 要登記 https://claude.ai/api/mcp/auth_callback。

客戶端需支援 MCP 的 OAuth 授權（授權碼＋PKCE），並能填入預先註冊的 Client ID：

設定項

值

Server URL

https://mcp.maiagent.ai/mcp

Transport

Streamable HTTP

OAuth Client ID

OAuth 應用程式的 Client ID

Redirect URI

客戶端實際使用的回呼網址，須登記在 OAuth 應用程式

授權伺服器的端點與協定細節見 MaiAgent 作為 OAuth 2.1 授權伺服器。

四、驗證連線

設定完成後，在您的 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 代表設定的認證已帶上。用 OAuth 連線時，auth_header_preview 會以 Bearer 開頭。organization_id 顯示 null 是正常的：要操作的組織由 API Key，或 OAuth 應用程式所屬的組織決定。實際能否呼叫成功，可以接著請 AI 執行一個查詢（例如「列出我的所有 Agent」）確認。

五、開始使用

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

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

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

六、疑難排解

症狀

可能原因與解法

呼叫 API 時回應 401

API Key 錯誤、已撤銷或停用。請確認格式為 Api-Key <YOUR_API_KEY>（Api-Key 與金鑰之間有一個空格）。

使用 API Key，客戶端卻要求登入或顯示需要驗證

設定裡沒有帶到 Authorization 標頭，MaiAgent MCP 因此要求客戶端改走 OAuth。請檢查標頭的設定方式；要用 OAuth 則依用 OAuth 連線設定 Client ID。

OAuth 授權時出現 Redirect URI 不符

客戶端的回呼網址和 OAuth 應用程式登記的不一致。請確認 scheme、主機、連接埠與路徑完全相同。

OAuth 授權頁無法登入

授權頁只提供 Email 與密碼登入，只用 SSO 登入的帳號請改用 API Key。

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

API Key 綁定的是「建立金鑰當下所在的組織」，請切換到正確的組織後重新建立金鑰，並更新設定檔。OAuth 操作的是應用程式所屬的組織，請改用正確組織的 Client ID。

工具清單是空的

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

Claude Code 顯示 Pending approval

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

執行 API 時出現權限錯誤

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

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

上一頁MCP（Model Context Protocol）

下一頁自架 MCP Server 接入規格

最後更新於 3 天前

這有幫助嗎？