MCP server
Gemini CLI MCP server 管理：stdio、HTTP、SSE、header、環境變數、啟停、reload、OAuth auth 和工具列表。
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 控制引數和路徑。