跳轉到

U-Office Force X - MCP Server 開發者手冊

本手冊提供給 第三方開發者、企業客戶、系統整合商（SI），透過 Model Context Protocol (MCP) 標準，安全的將您的 AI Agent（如 Claude, OpenAI Assistants, 或自建 LLM Agent 應用）無縫連接至 U-Office Force X 的系統，實現資料存取與自動化操作。若你過去已熟悉 REST API 開發，或使用過任何 AI Agent Framework（如 LangChain、LangGraph、Semantic Kernel 或 Agent Framework 框架），將能更快速掌握 MCP 的整合方式。當然您也可以選擇使用no-code/low-code 平台來進行整合開發，例如：n8n、Dify 等。

概觀介紹

  • 什麼是 U-Office Force X MCP-Server？ U-Office Force X MCP-Server 是為 AI Agent 設計的服務，讓開發者能以 AI Agent 業界標準化協定（Model Context Protocol）安全的操作 U-Office Force X 系統。透過 MCP，AI Agent 不需要理解複雜的 API 細節，傳統上的 API 設計，開發者需要充份了解 API 參數，撰寫固定的使用者操作介面，提供使用者操作以收集相關 API 參數，無法做到良好的 AI 應用使用者體驗，有了 MCP 協議，能以自然語言觸發業務行為，例如：查詢待辦資料、審核表單、檢視文件、查詢個人檔案等。

  • 什麼是 MCP (Model Context Protocol)？ MCP 是一種新的業界開放標準協定，目的在於解決「AI 模型」與「外部數據/工具」之間連接困難的問題，允許 AI Agent 與各種應用程式和服務進行互動。它定義了一組通用的 API 和資料格式，讓不同的 AI Agent 能夠以相同的方式存取和操作資料，實現 AI Agent Function Calling 機制，擴展　AI Agent 的能力。

U-Office Force X 提供的 MCP Server 可以讓您的 AI Agent 具備操作 U-Office Force X 產品的能力（視具體開放的 API 服務，U-Office Force X OpenAPI 服務）。整合後，您的 AI Agent 將獲得 Tools (工具) 能力，賦予 AI Agent 執行權限，例如：查詢待辦資料、審核表單、檢視文件、查詢個人檔案等。

  • MCP 協議架構說明
  • MCP Host (您的 AI Agent/Client): 這是您開發的 AI 應用程式（例如 Claude Desktop, Cursor, 或您自建的 AI Agent 應用）。
  • MCP Server (U-Office Force X MCP-Server): U-Office Force X 提供的 MCP-Server 服務端，負責將內部的資料或功能轉換成 MCP 標準格式。
  • Protocol: Host 與 Server 兩者之間透過標準的 JSON-RPC 訊息進行溝通。

身份驗證 (Authentication)

U-Office Force X MCP-Server 使用 OAuth 2.0 作為主要的身份驗證和授權機制。這確保了只有經過授權的 AI Agent 能夠存取 U-Office Force X 的資源和功能。U-Office Force X 提供了完整的 OAuth 2.0 流程，包含取得授權碼、交換存取權杖 (Access Token)、以及使用刷新權杖 (Refresh Token) 來延長存取權杖的有效期限。您的 AI Agent 需要實作整合 OAuth 身份驗證，以取得存取權杖 (Access Token)，並且自行管理存取權杖 (Access Token)以及刷新換發，以確保能夠順利與 MCP-Server 進行互動。

當使用者在 AI Agent 中觸發需要存取 U-Office Force X 資源的操作時，您 AI Agent 會使用先前取得的存取權杖 (Access Token) 向 MCP-Server 發出請求。MCP-Server 會驗證該存取權杖的有效性，並根據權杖中的權限來決定是否允許該請求。如果驗證成功，MCP-Server 將處理該請求並返回相應的資料或結果給 AI Agent。

  • OAuth 伺服器 URL
https://{your_uofx_domain}/oauth/authorize
  • OAuth Access Token URL
https://{your_uofx_domain}/api/oauth/token

alt text

如何取得 U-Office Force X OAuth-Server 身份驗證服務相關參數

U-Office Force X OAuth-Server 身份驗證服務需要在 U-Office Force X 系統中進行應用程式的註冊，取得相關的 Client ID 和 Client Secret以及授權 scopes。請依照以下步驟操作：

  1. 進入 U-Office Force X 管理者介面。
  2. 導航至「系統管理」/「金鑰管理」功能。
  3. 點擊「新增金鑰」按鈕。
  4. 填寫Client名稱，並選擇「開放授權金鑰(OAuth)」類型。
  5. 點擊「自動產生」按鈕以生成金鑰(Client Secret)。
  6. 並新增重新導向URL。
  7. 接著下一步設定授權範圍(Scopes)，根據您的 AI Agent 需求選擇適當的權限。
  8. 最後，點擊「儲存」按鈕完成應用程式註冊。

MCP 伺服器端點 (Endpoint)

在 MCP 協議中，MCP 伺服器端點是 AI Agent 與 MCP 伺服器進行通訊的主要入口點。該協議定義二種主要的通訊方式：Stdio (Standard Input/Output) 和 Streamable HTTP，其中 Streamable HTTP 是以遠端服務方式連接，而 Stdio 通常用於本地或嵌入式環境。Office Force X MCP-Server　採用的是 Streamable HTTP 方式，AI Agent 可以透過以下端點連接。

  • MCP 伺服器 URL
https://{your_uofx_domain}/mcp

常見問題

  • MCP Server 是否有內建LLM AI 功能？

    目前 U-Office Force X 提供的 MCP Server 本身並不包含任何 LLM AI 功能。它的主要功能是作為一個中介，讓您的 AI Agent 能夠透過 MCP 協議安全地存取 U-Office Force X 的開放 API服務(U-Office Force X OpenAPI 服務)。

  • 為什麼我的AI Agent無法調用Tool或是成功率不高

    如果您的 AI Agent 無法調用 U-Office Force X MCP Server 提供的工具 (Tools)，可能有以下幾個原因：

    1. OAuth 權限不足：請確認您的 OAuth 存取權杖 (Access Token) 是否包含了所需的授權範圍 (Scopes)，以存取特定的 U-Office Force X 資源。

    2. MCP 端點配置錯誤：請確認您的 AI Agent 是否正確配置了 MCP 伺服器的 URL。

    3. 請求格式錯誤：請確認您的 AI Agent 發出的 MCP 請求是否符合 MCP 協議的規範。

    4. 伺服器端問題：請檢查 U-Office Force X MCP Server 是否運行正常，並查看伺服器日誌以獲取更多錯誤資訊。

    5. 網路連接問題：請確認您的 AI Agent 能夠正常連接到 U-Office Force X MCP Server 的網路端點。

    6. LLM Model問題：MCP Server 只是提供工具功能，實際背後的原理為 LLM Model 的 Function Calling 機制，請確認您的 LLM 模型是否支援 Function Calling 機制。並且是否能正確解析 MCP Server 提供的工具 (Tools) 定義與 LLM Model 能力有關，多數現行的雲端平台閉源的生成式 AI 模型普遍能力較強，通常只要在AI Agent 的提示工程做些調整即可順利正確識別及調用 Function Calling ，但若為地端開源模型普遍能力較差，建議使用GPT-OSS 120B模型，搭配精心設計過的提示工程也可以有不錯效果。