> ## Documentation Index > Fetch the complete documentation index at: https://docs.kasoftware.com/llms.txt > Use this file to discover all available pages before exploring further. # 遠端 MCP 伺服器 > 透過內建的 Model Context Protocol（MCP）伺服器將 AI 用戶端連線到正在執行的知行之橋執行個體，用於診斷和執行維運操作。 知行之橋 內建一個 **MCP 伺服器**，可將 AI 用戶端（例如 Claude Desktop、GitHub Copilot、OpenAI Codex 或任何相容 MCP 的用戶端）直接連線到正在執行的 知行之橋 執行個體。之後，即可使用自然語言與 知行之橋 互動，詢問錯誤、日誌、設定、端口、檔案、憑證和整體系統健康狀況，並執行觸發端口、重新排入佇列訊息等維運操作。 MCP 伺服器預設啟用，共提供 18 個工具：15 個診斷工具，以及 3 個對 知行之橋 執行個體執行操作的操作工具。無需在 知行之橋 UI 中進行任何設定；此功能本身就是供外部 AI 用戶端連線的 MCP 伺服器端點。 > [!WARNING] > > 使用 AI 助手可能會將 知行之橋 中的資料傳送給第三方 AI 服務。請先確認組織的資料處理政策和所用服務的條款。AI 生成的結果可能不準確，應在執行操作前進行驗證。如需幫助，請聯絡 知行軟件 技術支援。 如需為 知行之橋 本身設定 AI 提供者（用於產品內的 AI 功能），請參閱 [AI 設定](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/getting-started/administration/settings/ai-settings.md)。 ## 連線 AI 用戶端 MCP 伺服器端點為： ``` https://:/mcp.rsc ``` 身分驗證使用 `x-cdata-authtoken` 標頭和有效的 知行之橋 使用者 Authtoken。要產生 Authtoken，請在[使用者](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/users.md)頁面開啟該使用者的 **API 存取**索引標籤，勾選**啟用 Authtoken 存取**，然後複製系統產生的 Authtoken。 ### 安全儲存 Authtoken 下面的用戶端設定範例將 Authtoken 作為內嵌值寫在設定檔中。這種方式可以正常運作，但共用工作站上的設定檔可能會被其他本機使用者讀取，或被意外提交到版本控制系統。將權杖儲存在作業系統環境變數中，可以避免將其寫入設定檔本身。 **Linux 和 macOS** 將以下這行新增到 shell 設定檔（`~/.bashrc`、`~/.zshrc` 或 `~/.profile`）中，然後重新載入該檔案： ```bash theme={null} export ARC_AUTHTOKEN="your-authtoken" ``` **Windows** 開啟命令提示字元並執行： ``` setx ARC_AUTHTOKEN "your-authtoken" ``` 此命令會設定一個持續性的使用者層級環境變數。執行該命令後，請重新啟動所有已開啟的終端機或應用程式，使其讀取新變數。 #### 在用戶端設定檔中參照變數 **GitHub Copilot CLI** 和 **OpenAI Codex** 用戶端都從終端機啟動，並繼承完整的系統環境，因此可以直接讀取系統環境變數。各用戶端的安全設定方法請見下文對應章節。 **Claude Desktop** 不會像從終端機啟動的處理程序那樣繼承完整的系統環境，因此在其設定 JSON 中參照環境變數無效。請改用下文 [Claude Desktop](#claude-desktop) 一節中介紹的 `--header-file` 方法。 儲存以下任一設定後，請重新啟動 AI 用戶端工作階段。 ### Claude Desktop Claude Desktop 透過 `stdio` 與 MCP 伺服器通訊（它會啟動一個本機子處理程序，並透過 `stdin/stdout` 進行通訊），因此無法直接連線到 知行之橋 的遠端 HTTP 端點。`mcp-remote` npm 套件可以彌補這個落差：它作為本機 stdio 處理程序執行，供 Claude Desktop 與之通訊，並將請求轉送到 知行之橋 的 HTTP 端點。 `--transport http-only` 旗標指示 `mcp-remote` 在與 知行之橋 通訊時使用純 Streamable HTTP，從而略過任何協商 SSE（Server-Sent Events）的嘗試。`mcp.rsc` 端點不支援 SSE，因此此旗標可避免不必要的後援延遲或連線錯誤。 將以下內容新增到 Claude Desktop 設定檔中（**Settings > Developer > Edit Config**）： ```json theme={null} { "mcpServers": { "arc-mcp": { "command": "npx", "args": ["-y", "mcp-remote", "https://:/mcp.rsc", "--transport", "http-only", "--header", "x-cdata-authtoken:"] } } } ``` > [!NOTE] > > 如果使用 Windows，請使用 `"command": "cmd"`，並在 `"npx"` 前加上 `"cmd", "/c"` 前置字串。 #### 使用 `--header-file` 參照權杖的替代方法 Claude Desktop 的設定 JSON 不支援參照環境變數，因為它啟動子處理程序時不經過 shell。要避免將 Authtoken 寫入設定檔，請改用 `mcp-remote` 的 `--header-file` 旗標。 在 Claude Desktop 可以存取的任意位置建立一個純文字檔案（例如 `/home//.cdata/arc-mcp-headers.txt`），並新增以下這行： ``` x-cdata-authtoken: ``` 然後限制該檔案的權限，使只有目前的使用者帳戶可以讀取： **macOS 和 Linux**： ```bash theme={null} chmod 600 /home//.cdata/arc-mcp-headers.txt ``` **Windows**（命令提示字元）： ``` icacls "C:\Users\\.cdata\arc-mcp-headers.txt" /inheritance:r /grant:r "%USERNAME%:R" ``` 然後更新設定，使用 `--header-file` 取代 `--header`： ```json theme={null} { "mcpServers": { "arc-mcp": { "command": "npx", "args": ["-y", "mcp-remote", "https://:/mcp.rsc", "--transport", "http-only", "--header-file", "/home//.cdata/arc-mcp-headers.txt"] } } } ``` > [!NOTE] > > 如果使用 Windows，請使用 `"command": "cmd"`，在 `"npx"` 前加上 `"cmd", "/c"` 前置字串，並使用 Windows 路徑，例如 `C:\Users\\.cdata\arc-mcp-headers.txt`（在 JSON 字串中，每個反斜線都要寫成 \）。 儲存後，結束並重新開啟 Claude Desktop，然後在新聊天的 **Tools/Search** 功能表中啟用 `arc-mcp` 伺服器。 ### GitHub Copilot CLI 與 Claude Desktop 不同，GitHub Copilot CLI 可以直接透過 HTTP 連線遠端 MCP 伺服器，因此不需要 `mcp-remote` 橋接，而是直接指向 知行之橋 端點。其 MCP 設定檔的位置取決於作業系統： | 作業系統 | 設定檔位置 | | - | - | | macOS / Linux | `~/.copilot/mcp-config.json` | | Windows | `C:\Users\\.copilot\mcp-config.json` | 編輯該檔案並新增以下內容： ```json theme={null} { "mcpServers": { "arc-mcp": { "url": "https://:/mcp.rsc", "type": "http", "headers": { "x-cdata-authtoken": "" } } } } ``` #### 使用環境變數安全儲存權杖 GitHub Copilot CLI 支援在 `headers` 欄位中使用 `${VAR}` 替換。將內嵌的 Authtoken 值替換為對 `ARC_AUTHTOKEN` 變數的參照： ```json theme={null} { "mcpServers": { "arc-mcp": { "url": "https://:/mcp.rsc", "type": "http", "headers": { "x-cdata-authtoken": "${ARC_AUTHTOKEN}" } } } } ``` 啟動 Copilot CLI 之前，必須將 `ARC_AUTHTOKEN` 設定為系統或使用者環境變數。有關設定說明，請參閱[安全儲存 Authtoken](#安全儲存-authtoken)。 儲存後，啟動新的 Copilot CLI 工作階段，使其載入 `arc-mcp` 伺服器。 ### OpenAI Codex 與 Copilot CLI 一樣，OpenAI Codex 直接支援遠端 HTTP MCP 伺服器，因此不需要橋接，可以直接連線到 知行之橋 端點。其設定檔的位置取決於作業系統： | 作業系統 | 設定檔位置 | | - | - | | macOS / Linux | `~/.codex/config.toml` | | Windows | `C:\Users\\.codex\config.toml` | 此設定在 Codex CLI、Codex IDE 擴充功能和 Codex Desktop 之間共用。編輯該檔案並新增以下內容： ```toml theme={null} [mcp_servers.arc-mcp] url = "https://:/mcp.rsc" http_headers = { "x-cdata-authtoken" = "" } ``` #### 使用環境變數安全儲存權杖 OpenAI Codex 提供獨立的 `env_http_headers` 欄位，用於將標頭名稱對應到環境變數名稱，而不是內嵌值。將 `http_headers` 替換為 `env_http_headers`： ```toml theme={null} [mcp_servers.arc-mcp] url = "https://:/mcp.rsc" env_http_headers = { "x-cdata-authtoken" = "ARC_AUTHTOKEN" } ``` 啟動 Codex 之前，必須將 `ARC_AUTHTOKEN` 設定為系統或使用者環境變數。有關設定說明，請參閱[安全儲存 Authtoken](#安全儲存-authtoken)。 儲存後，重新啟動 Codex（或啟動新工作階段），使其載入 `arc-mcp` 伺服器。 ## 關聯 ID 知行之橋 會為從單一進入點開始的工作（輸入 HTTP 請求、AS2 或 SFTP 工作階段、排程觸發或 Flow API 呼叫）標記一個關聯 ID（correlation Id），並將其傳遞到由此產生的交易、應用程式日誌項目、請求日誌項目和服務日誌工作階段中。下文中的多個診斷工具會在可用時傳回此 ID，方便將同一工作單元的相關證據關聯起來。 ## 可用工具 ### 診斷工具 以下 15 個工具為唯讀工具，不會修改 知行之橋 執行個體上的任何資料或狀態。
工具 說明
`find_workspaces`列出並檢查 知行之橋 工作區，包括端口摘要以及近期的交易數和錯誤數。
`find_connectors`依工作區或類型瀏覽端口；深入檢視端口的設定、工作流程連線、參照的憑證和錯誤率。
`find_messages`依端口、狀態、方向、時間範圍或訊息 ID 搜尋交易訊息。擷取訊息詳細資訊，包括訊息標頭和交易日誌內容。
`find_files`在 Send、Receive 或 Sent 資料夾中搜尋端口訊息檔案。依名稱擷取檔案內容。
`find_logs`依嚴重性層級、時間範圍或訊息文字查詢應用程式日誌。在可用時傳回關聯 ID 欄位，用於將日誌項目與相關交易和服務日誌工作階段關聯起來。
`find_requests`檢查 API 請求日誌，用於稽核和疑難排解（可依方法、URL、使用者、IP 或時間範圍篩選）。在可用時傳回關聯 ID 欄位。
`find_certificates`尋找憑證、檢查到期日期，並依端口使用情況或類別（Public 或 Private）篩選。
`find_vault_entries`依名稱、類型或標籤搜尋配置庫項目。加密值永遠不會公開。
`find_reports`瀏覽報表定義，並檢查排程、資料行、篩選條件和電子郵件收件者設定。
`find_flow_apis`瀏覽 Flow API 定義，或取得某個 API 的請求和回應設定。
`find_service_logs`尋找端口服務日誌（AS2、AS4、GISB、RNIF、FTP Server、OFTP、SFTP Server、TCP Server、AMQP、IDoc、MQTT），並擷取某一日誌的內容。適用於排查未產生交易記錄的連線、接聽程式和通訊協定層級失敗。
`diagnose_message`依訊息 ID 或交易 ID 診斷特定交易訊息。傳回完整的訊息詳細資訊（訊息標頭和交易日誌內容）。存在關聯 ID 時，還會傳回該訊息相關的請求日誌項目、應用程式日誌項目和服務日誌證據。
`trace_message_flow`在提供訊息 ID，或提供檔名和端口時，端對端追蹤訊息在工作流程中跨端口流轉的過程。
`check_health`取得 知行之橋 執行個體的健康狀況快照：錯誤數、即將到期的憑證、授權狀態、記憶體和磁碟警告，以及各端口的失敗率和訊息積壓情況。
`describe_profile`依區段檢視 知行之橋 個人設定（應用程式、AS2、SFTP 等）。機密值會被遮蔽。
### 操作工具 18 個工具中有 3 個會對 知行之橋 執行個體執行實際操作，而不僅僅是讀取資料。執行這些工具之前，AI 用戶端會請求您明確確認。以下防護措施適用於全部 3 個工具： * **需要確認。** 未經您事先明確確認，AI 用戶端無法執行任何操作。 * **沿用現有權限。** 使用者只能觸發、重新排入佇列或清理其 知行之橋 權限已允許的資源。只有唯讀存取權限的使用者完全無法呼叫操作工具。 * **必須指定目標。** 每個操作都會指定其影響的具體工作區和端口，不會推斷或猜測任何內容。 * **操作會被稽核。** 每個操作都會寫入一筆稽核記錄，標明執行了什麼操作、針對哪個端口以及結果如何。 要檢視或調整權限，請參閱[使用者角色](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/getting-started/administration/settings/user-roles.md)。
工具 說明
`trigger_connector`執行端口的接收或傳送操作，可選擇針對特定檔案或訊息。
`requeue_message`將先前已處理的訊息重新排入佇列，使端口再次處理該訊息，等同於**交易**索引標籤上的**重新排隊**操作。
`cleanup_files`針對單一端口、單一工作區或所有工作區執行[已設定的批次清理](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/getting-started/administration/settings/cleanup-settings.md)，歸檔或刪除早於指定天數的資料。
## 範例提示 透過 AI 用戶端，可以使用自然語言與 知行之橋 互動。診斷提示範例包括： * 「分析訊息 EDIFACT1-20260513-123047000-wxcU 的失敗原因，並提供修正建議。」 * 「顯示過去 24 小時內所有提到 AS2 的錯誤日誌。」 * 「哪些憑證將在未來 30 天內到期？」 * 「追蹤訊息 AS2\_Inbound-20260623-001 在其工作流程中的流轉過程。」 * 「檢查生產工作區的健康狀況。」 * 「列出所有 SFTP 端口。」 * 「顯示今天上午各工作階段的 SFTP Server 服務日誌。」 對於操作工具，AI 用戶端會在繼續之前請求您確認。例如： * **您：** 將 Production 工作區中 AS2\_Outbound 端口上的訊息 AS2\_Outbound-20260814-001 重新排入佇列。 * **AI 用戶端：** 我將把 Production 工作區中 AS2\_Outbound 端口上的訊息 AS2\_Outbound-20260814-001 重新排入佇列。這會使端口再次處理該訊息。是否要繼續？ * **您：** 是。 * **AI 用戶端：** 已完成。該訊息已重新排入佇列。 ## 安全性說明 * MCP 伺服器遵循 知行之橋 現有的身分驗證和授權機制。使用者只能看到其有權存取的資料。 * 請一律透過 HTTPS 連線。每次呼叫時，`x-cdata-authtoken` 都會在請求標頭中傳送；如果使用純 HTTP，它會在傳輸過程中外洩。僅在針對 `localhost` 進行測試時使用 `http://`。 * 工具回應中的敏感值（密碼、權杖和私密金鑰）會被遮蔽。 * 永遠不會傳回加密的配置庫項目值。 * 請將 Authtoken 儲存在作業系統環境變數中，而不是作為內嵌值寫入用戶端設定檔。請參閱[安全儲存 Authtoken](#安全儲存-authtoken)。 * 操作工具在執行任何操作之前都需要使用者明確確認，而且每個操作都會被稽核。只有唯讀存取權限的使用者無法呼叫操作工具。 ## 本版本的已知限制 * 在詳細模式下傳回的大型訊息承載資料可能較大，可能會影響 AI 用戶端的權杖用量。 * 服務日誌依工作階段擷取。當一個工作階段涉及多個檔案時，`diagnose_message` 傳回的關聯證據可能包含同一工作階段中的其他檔案。這是預期行為。 * 關聯 ID 涵蓋主要的訊息處理路徑。某些路徑（例如某些排程重試工作處理程序）可能不帶有關聯 ID。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.