> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/mcp/remote-mcp.md).
# Remote MCP 服務概述
Remote MCP（遠端 MCP 服務）的概念，以及 MaiAgent 怎麼連線 Composio、Zapier 等託管服務與自架的 MCP 伺服器：傳輸方式、驗證、工具範圍、逾時與紀錄，和使用時的注意事項。
> 本頁假設您已了解 MCP 的基本概念，見 [MCP（Model Context Protocol）](/tech/mcp/mcp-model-context-protocol.md)。
## 1. 為何選擇 Remote MCP 服務？
一般而言，MCP 伺服器有兩種執行方式：由用戶端在本機啟動（stdio），或部署成網路服務、讓用戶端透過 HTTP 連線。後者稱為 Remote MCP。Composio、Zapier 等託管型服務替您部署好伺服器，並代管各 SaaS 應用的授權，您只要取得一個伺服器網址就能使用。
| 考量面向 | 自行架設 MCP 伺服器 | 託管型 Remote MCP 服務 |
| --------- | ---------------- | ------------------------ |
| **部署與維運** | 自行部署、監控與更新 | 由服務商負責 |
| **第三方授權** | 自行實作 OAuth 或管理金鑰 | 通常由服務商代管，伺服器網址或標頭就代表您的授權 |
| **可用工具** | 依自己的系統需求開發 | 依服務商支援的應用與動作 |
| **資料路徑** | 資料只經過您的伺服器 | 工具參數與結果會經過服務商 |
常見應用場景：
* **辦公自動化**：讀取或寄送 Gmail、管理 Google Calendar 行程、搜尋 Google Drive 文件、更新 Google Sheets。
* **客服與工單**：在 Zendesk、Salesforce 等系統查詢客戶資料、建立或更新工單。
* **專案與開發協作**：在 Jira、Asana、Linear、GitHub 建立 Issue、更新任務狀態。
***
## 2. MaiAgent 怎麼連線 Remote MCP
MaiAgent 是 **MCP Client**：Agent 只決定要呼叫哪個工具與參數，實際連線由平台送出。託管服務與您自架的伺服器，走的是同一套連線方式。
```mermaid
sequenceDiagram
participant A as Agent（LLM）
participant P as MaiAgent 平台（MCP Client）
participant S as Remote MCP 伺服器
participant X as 外部服務（Gmail、Jira…）
P->>S: initialize → tools/list（帶設定的標頭或 OAuth 權杖）
S-->>P: 工具清單
P->>P: 依「允許的工具」過濾後交給模型
A->>P: 工具呼叫（名稱＋JSON 參數）
P->>S: 新開 session：initialize → tools/call
S->>X: 呼叫外部服務 API
X-->>S: 回應
S-->>P: 工具結果
P->>P: 轉成文字、截斷過長內容、寫入工具執行紀錄
P-->>A: 工具結果
```
| 項目 | MaiAgent 的行為 |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **傳輸方式** | 支援 Streamable HTTP 與 SSE，依網址判斷：路徑結尾為 `/sse`、路徑中含 `/sse/`，或 query string 帶 `transport=sse` 時走 SSE，其餘走 Streamable HTTP。不支援 stdio，也不支援 WebSocket。 |
| **網址** | 必須是 `https://`、可從網際網路連線的位址；內部網路位址無法儲存，地端部署需要時請洽 MaiAgent。 |
| **驗證** | 三種方式：網址本身帶授權（Composio、Zapier 提供的伺服器網址屬於這種）；在「標頭 (JSON)」放固定的 API Key；選擇 OAuth 連接器，由平台代為完成授權並自動更新權杖。需要每位使用者用自己的權杖時，可另外設定聯絡人 MCP 憑證。 |
| **何時取得工具清單** | 每次組裝 Agent 的工具時都會向伺服器執行 `tools/list`，所以伺服器端移除的動作，下一次回覆就不會再提供給模型。 |
| **工具範圍** | 每個 MCP 工具（一個伺服器網址）有自己的「允許的工具 (JSON 數組)」清單，Agent 綁定這個 MCP 工具後，只能呼叫清單內的工具。伺服器新增的動作**不會自動開放**，要回到工具設定點「重新取得」後再開啟。 |
| **逾時與重試** | MCP session 的讀取逾時為 30 秒。連線中斷等暫時性錯誤只對讀取類（重送也安全）的工具自動重試，最多 3 次。 |
| **紀錄與計費** | 每次呼叫都寫入工具執行紀錄（工具、實際呼叫的 MCP 工具名稱、輸入參數、輸出或錯誤、耗時）。成功呼叫依讀取類或寫入類扣 Credits，額度不足時呼叫不會送出。 |
連線、驗證、重試與錯誤處理的完整規格，見 [自架 MCP Server 接入規格](/tech/mcp/self-hosted-mcp-server.md)。
### 兩個使用入口
* **Agent 的 MCP 工具**：在後台建立 MCP 工具，填入伺服器網址與驗證方式，再綁定到 Agent。適合對外的客服 Agent 或特定用途的 Agent。
* **MaiGPT 連接器**：管理員啟用連接器後，成員在 MaiGPT 對話中自行授權並開關使用。
***
## 3. 限制與注意事項
* **伺服器網址就是憑證**：Composio、Zapier 等服務產生的伺服器網址本身帶有授權，取得網址的人就能以您的帳號呼叫工具。只填在 MaiAgent 的工具設定，不要放進角色指令、對話或公開文件；外洩時請到服務商端重新產生。
* **所有使用者共用同一個帳號**：用網址或固定標頭驗證時，所有透過這個 Agent 對話的使用者，都會以當初在服務商端授權的帳號操作。個人帳號型的服務（個人信箱、個人行事曆）請改用聯絡人個別授權的 OAuth 連接器，或只在內部 Agent 使用。
* **不同 Agent 要不同權限時，建立不同的 MCP 工具**：允許的工具清單設在 MCP 工具上，綁定同一個 MCP 工具的 Agent 共用同一份清單。
* **資料會經過第三方**：一般而言，託管服務會經手工具參數與結果，請依資料分類與法規要求評估。
* **先開讀取、再開寫入**：只開放 Agent 需要的動作。寫入類動作不會自動重試，但模型仍可能重複呼叫，建立、寄送、刪除等動作請確認服務端的行為。
* **本機型 MCP 伺服器要改成遠端版本**：以 `npx`、`node` 等指令在本機啟動的 MCP 伺服器無法直接使用，請改用服務商提供的遠端版本，或自行部署成 HTTP 服務。
***
## 4. 操作請看使用手冊
* [建立 MCP 工具](https://docs.maiagent.ai/build/tools/mcp-setup)：網址、標頭、OAuth 連接器、允許的工具
* [為 Agent 配置工具](https://docs.maiagent.ai/build/tools/configure_tools)
* [聯絡人 MCP 憑證設定](https://docs.maiagent.ai/build/tools/setup-contacts-mcp-credentials)
* [MaiGPT 連接器](https://docs.maiagent.ai/work/maigpt/connectors)、[管理連接器（管理員）](https://docs.maiagent.ai/work/maigpt/connectors/connectors-admin)
* [工具執行紀錄](https://docs.maiagent.ai/build/agent-ops/tool-execution-records)
服務商的設定步驟見 [Composio 串接](/tech/mcp/composio.md)、[Zapier 串接](/tech/mcp/zapier.md)。
***
### 參考連結
* [Model Context Protocol 規格：傳輸方式（Transports）](https://modelcontextprotocol.io/specification/latest/basic/transports)
* [Model Context Protocol 規格：授權（Authorization）](https://modelcontextprotocol.io/specification/latest/basic/authorization)
* [Model Context Protocol 規格 2024-11-05：HTTP with SSE 傳輸](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.maiagent.ai/tech/mcp/remote-mcp.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.