MCP（Model Context Protocol）讓 AI 專家和機器人能夠呼叫外部工具——網路搜尋、程式碼執行器、資料庫、API——無需你撰寫任何整合程式碼。連接的每台 MCP 伺服器都會成為 Yao Agents 中所有 AI 助手可用的工具集。
---
## 運作原理
MCP 工具以 `.mcp.yao` 檔案的形式設定，存放在應用程式目錄下的 `mcps/` 目錄中。Yao Engine 啟動時會載入所有 MCP 檔案，並將其工具提供給每位 AI 專家和機器人使用。
Yao Agents 支援四種連接外部 MCP 伺服器的方式：
| 傳輸方式 | 適用場景 |
|---------|---------|
| `http` | MCP 伺服器提供標準 HTTP 端點（雲端服務最常見）|
| `sse` | 伺服器使用 Server-Sent Events（較早期的 MCP 部署）|
| `stdio` | 伺服器是透過命令列啟動的本地程序 |
| `process` | MCP 伺服器以 Yao 腳本實作，不需要外部程序（供開發者使用）|
---
## 連接 HTTP MCP 伺服器
最簡單的方式：將 Yao 指向一個現有的 MCP 相容 HTTP 端點。
在 `mcps/` 目錄下建立檔案，例如 `mcps/my-server.mcp.yao`：
```json
{
"label": "我的 MCP 伺服器",
"description": "這台伺服器的功能描述",
"transport": "http",
"url": "https://my-mcp-server.example.com/mcp",
"authorization_token": "Bearer sk-...",
"timeout": "30s"
}
```
重新啟動 Yao Engine，該伺服器提供的工具會自動出現在每位 AI 專家和機器人中。
### HTTP 連接欄位說明
| 欄位 | 必填 | 說明 |
|------|------|------|
| `label` | ✓ | UI 中顯示的名稱 |
| `description` | | 簡要描述這台伺服器提供的功能 |
| `transport` | ✓ | `"http"` |
| `url` | ✓ | MCP 端點完整 URL（如 `https://example.com/mcp`）|
| `authorization_token` | | Bearer token 或 API 金鑰，發送到 `Authorization` 請求標頭 |
| `timeout` | | 請求逾時時間，支援 `30s`、`5m`、`1h` 格式，預設 `30s` |
| `tags` | | 標籤陣列，用於在 UI 中篩選 |
| `enable_sampling` | | 允許伺服器向 Yao 發起 LLM 補全請求（預設 `false`）|
| `enable_roots` | | 與伺服器共享工作區根目錄清單（預設 `false`）|
### 範例
```json
{
"label": "天氣 API",
"description": "取得任意地點的當前天氣和預報",
"tags": ["weather", "api"],
"transport": "http",
"url": "https://weather-mcp.example.com/mcp",
"authorization_token": "Bearer $ENV.WEATHER_API_KEY",
"timeout": "15s"
}
```
---
## 連接 stdio MCP 伺服器
當 MCP 伺服器是由 Yao 依需求啟動的本地二進位檔案或腳本時，使用 `stdio`。
```json
{
"label": "本地 Python 工具",
"description": "執行本地 Python MCP 伺服器",
"transport": "stdio",
"command": "python3",
"arguments": ["/path/to/mcp_server.py"],
"env": {
"API_KEY": "$ENV.MY_API_KEY"
},
"timeout": "60s"
}
```
### stdio 專用欄位
| 欄位 | 必填 | 說明 |
|------|------|------|
| `command` | ✓ | 要執行的程式（如 `python3`、`node`、`npx`）|
| `arguments` | | 傳遞給命令的參數陣列 |
| `env` | | 子程序的環境變數，支援 `$ENV.變數名稱` 替換 |
---
## 套用設定變更
新增或修改 `.mcp.yao` 檔案後，重新啟動 Yao Engine 使變更生效。
---
## 內建 MCP 伺服器
Yao Agents 內建兩個 MCP 伺服器（使用 `process` 傳輸，不需要外部伺服器）：
| 伺服器 | 工具 | 說明 |
|-------|------|------|
| Web Tools | `search`、`fetch_html`、`fetch_markdown` | 網路搜尋和網頁內容擷取 |
| Image Generation | `generate`、`list_models` | 從文字提示產生圖像 |
這兩個伺服器自動啟用，無需任何設定。
---
## 進階：自訂 MCP 伺服器
若需要使用 Yao 腳本建立自己的 MCP 伺服器，包括 `process` 傳輸、工具/資源/提示映射和 SSE——請參閱 [Yao 開發者文件 → MCP 工具](https://yaoapps.com/docs/documentation/en-us/ai-agent-system/mcp-tools)（供開發者使用）。
MCP 工具
feedback
Feedback