接入 AI 客戶端（IDE Integration）

ServBay 可將內建的 MCP Server 一鍵整合到你常用的 AI 客戶端，會自動寫入對應的 MCP 設定，無需手動編輯設定檔。本說明將介紹整合流程、支援哪些客戶端，以及各客戶端的整合方式。

前提條件

• 已安裝並啟動 ServBay。
• 已安裝目標 AI 客戶端（ServBay 會根據設定判斷是否可整合）。

一鍵整合

進入 ServBay 設定（Settings）→ AI 客戶端整合（IDE Integrations），在客戶端列表中找到目標客戶端，點擊 整合（Integrate）。ServBay 會自動：

1. 定位發行包內嵌的 servbay-mcp 執行檔（無需單獨安裝）。
2. 依目標客戶端的設定規範寫入 MCP 設定（只新增／更新 servbay 節點，保留你既有的其他 MCP 設定）。
3. 顯示整合狀態。

如需解除整合，點擊 移除（Remove） 即可。

整合狀態

每個客戶端會顯示其與「本機 ServBay」的整合狀態：

狀態	意義
已整合	客戶端已指向本機這份 ServBay 的 servbay-mcp
已整合（其他路徑）	客戶端有設 servbay 但指向其他路徑（如另一份 ServBay）
未整合	偵測到該客戶端，但尚未整合
未偵測到	本機未找到該客戶端

支援的客戶端與整合方式

客戶端	整合方式	設定位置
Claude Code	官方 CLI：claude mcp add --scope user --transport stdio servbay -- <bin>	Claude Code 使用者級 MCP 設定
Codex	官方 CLI：codex mcp add（CLI 無效時會寫入 ~/.codex/config.toml）	Codex 設定
Cursor	寫入 ~/.cursor/mcp.json（頂層 mcpServers）	~/.cursor/mcp.json
VS Code / GitHub Copilot	寫入使用者級 mcp.json（頂層 servers，type: stdio）	VS Code 使用者級 mcp.json
Claude Desktop	寫入 claude_desktop_config.json（頂層 mcpServers）	claude_desktop_config.json

設定 schema 差異

不同客戶端的 MCP 設定頂層鍵名略有不同：VS Code 使用 servers，Cursor / Claude Desktop 則用 mcpServers。ServBay 會根據各客戶端規範自動寫入正確的鍵名，無需你手動處理。

驗證整合

整合後，可在相對應的 AI 客戶端發起與環境相關的請求（例如「列出 ServBay 目前運行的服務」），如 AI 可返回實際服務清單，則表示整合成功。

常見問題（FAQ）

• Q：整合會覆蓋我既有的 MCP 設定嗎？
  • A：不會。ServBay 只會新增／更新 servbay 節點，保留你的其他 MCP Server 設定。
• Q：客戶端顯示「未偵測到」？
  • A：代表本機尚未找到此客戶端。請先安裝並啟動一次後再執行整合。
• Q：整合後 AI 無法調用？
  • A：請確認 ServBay 正在運行；對於使用 CLI 整合的 Claude Code / Codex，請確認官方 CLI 可正常使用。可先移除再重新整合。
• Q：整合後建議進行哪些操作？
  • A：建議安裝 AI 規則，引導 AI 優先並正確使用 ServBay MCP。

總結

透過「AI 客戶端整合」，可將 ServBay MCP 一鍵接入主流 AI 工具，無需手動更改設定且不影響既有配置。整合完成後，搭配 AI 規則，即可讓 AI 流暢地管理你的本地開發環境。