MCP server
Gemini CLI MCP server 管理：stdio、HTTP、SSE、header、環境變數、啟停、reload、OAuth auth 和工具列表。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| MCP server | server | 對外提供能力的 MCP 服務。 |
| 自建 server | build | 自己實現一個 MCP server。 |
| 安全邊界 | scope | server 暴露和限制什麼。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你規劃構建或接入一個 MCP server，守住安全邊界。
你是 Gemini CLI MCP server 顧問。
【角色】
Gemini CLI MCP server 顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。
【輸入】
- 我想接入還是自建 server：___
- 它要提供什麼能力：___
- 涉及的資源和許可權：___
- 本地還是團隊共享：___
- 經驗水平：___
【工作流程】
1. 判斷接入現成還是自建
2. 若自建給最小結構
3. 限定 server 暴露的能力和許可權
4. 說明安全和審計
5. 給驗證
【輸出規範】
▌一、接入 vs 自建
▌二、自建最小結構（若需）
▌三、暴露能力與許可權
▌四、安全 + 驗證
【硬約束】
- 只暴露必要能力，不開放高危操作
- 憑據安全處理
- 團隊共享 server 注意認證審計
- 不要替我臆測情況或編造不存在的工具能力，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法Gemini CLI 支援設定和管理 MCP server。官方 command reference 中 /mcp 可 list、reload、enable、disable、auth、schema；CLI cheatsheet 裡也有 gemini mcp add/remove/list。
MCP server 是 Gemini CLI 和外部系統之間的橋。它可以暴露 tools，也可以暴露 resources。Tools 是動作，resources 是可讀上下文；設計 MCP 時應先開放 resources，再開放寫工具。
MCP server 的關鍵不是“能連上”，而是它暴露了哪些工具、拿到了哪些憑據、寫操作是否仍受確認和 policy 控制。
常見 transport
| 型別 | 適合 |
|---|---|
| stdio | 本地命令或 Docker server |
| HTTP | 本地或遠端 HTTP MCP endpoint |
| SSE | Server-sent events endpoint |
| 場景 | 推薦 transport | 說明 |
|---|---|---|
| 本地 CLI / Docker server | stdio | 易於本機除錯和隔離 |
| 內網服務 | HTTP | 適合已有服務化 endpoint |
| 遠端事件流 | SSE | 適合需要持續事件連線的 server |
| 需要瀏覽器 OAuth | HTTP / SSE | headless 環境要提前處理回撥問題 |
示例
HTTP server 可以用 gemini mcp add api-server http://localhost:3000 --transport http。SSE endpoint 可以用 --transport sse。需要 header 時用 --header 傳入，但不要把真實 token 寫進共享文件或儲存庫。
在 settings.json 裡，stdio server 通常使用 command、args、env、cwd；遠端 server 使用 url 或 httpUrl，可加 headers、timeout、includeTools、excludeTools、trust。trust: true 會繞過該 server 的工具確認，除非是企業內部強信任 server，否則不要預設開啟。
trust: true 邊界
trust: true 只適合你完全控制、工具引數可審計、失敗後果可接受的 server。公開教學和團隊預設設定裡，不建議把它當成省確認步驟的快捷方式。尤其是 GitHub、資料庫、雲資源、檔案系統、釋出系統這類 server，寫操作應該保留確認或 policy 限制。
更穩的做法是先用 includeTools 只開放必要工具，再用 excludeTools 禁掉高風險動作，最後用 policy 約束引數。
環境變數和脫敏
Gemini CLI 會對繼承自宿主環境的敏感變數做自動 redaction，例如包含 TOKEN、SECRET、PASSWORD、KEY、AUTH、CREDENTIAL 的變數。要把某個變數傳給指定 MCP server，必須在該 server 的 env 中顯式宣告。
這不是麻煩，而是知情同意：你明確告訴 CLI“這個 server 可以拿到這個變數”。即便如此，也應使用 $VAR 或 ${VAR} 引用，不要硬編碼明文。
OAuth remote MCP
遠端 SSE / HTTP MCP server 支援 OAuth 2.0。server 返回 401 後，CLI 可發現 OAuth endpoints、開啟瀏覽器認證、儲存 token 並重試連線。這個流程要求本機能開啟瀏覽器並接收 localhost callback；headless 環境通常不適合這種互動式 OAuth。
互動式命令
互動式會話裡常用 /mcp list、/mcp reload、/mcp disable <server>、/mcp enable <server>、/mcp auth <server>、/mcp schema。
排錯順序
- server 是否能單獨啟動。
- 環境變數是否存在。
- token scope 是否足夠。
- transport 是否設定正確。
/mcp reload後是否能列出工具。includeTools/excludeTools是否把目標工具過濾掉。- 遠端 OAuth 是否能完成瀏覽器回撥。
驗收方式
驗收一個 MCP server，要覆蓋連線、工具發現、resource 讀取、只讀工具呼叫、寫工具確認五項。只驗證“能連上”不夠；很多風險出在工具許可權和憑據傳遞。
接下來去哪
MCP resources
先暴露只讀 resources，再考慮有副作用的 tools。
MCP 設定
回看 settings.json、環境變數和憑據傳遞的最小許可權做法。
Policy engine
寫操作工具需要繼續用 policy 控制引數和路徑。