MCP 伺服器

{ ...檔案包含其他設定物件
  "mcpServers": {
    "serverName": {
      "command": "path/to/server",
      "args": ["--arg1", "value1"],
      "env": {
        "API_KEY": "$MY_API_TOKEN"
      },
      "cwd": "./server-directory",
      "timeout": 30000,
      "trust": false
    }
  }
}

設定屬性

每個伺服器設定支援以下屬性：

必要（以下之一）

command (字串): Stdio 傳輸的可執行檔路徑。
url (字串): SSE 端點 URL (例如 "http://localhost:8080/sse")。
httpUrl (字串): HTTP 串流端點 URL。

選用

args (字串[]): Stdio 傳輸的命令列參數。
headers (物件): 使用 httpUrl 時的自訂 HTTP 標頭。
env (物件): 伺服器處理程序的環境變數。值可以使用 $VAR_NAME 或 ${VAR_NAME} 語法參考環境變數。
cwd (字串): Stdio 傳輸的工作目錄。
timeout (數字): 請求逾時（毫秒）（預設值：600,000 毫秒 = 10 分鐘）。
trust (布林值): 若為 true，則繞過此伺服器的所有工具呼叫確認（預設值：false）。

設定範例

Python MCP 伺服器 (Stdio)

{
  "mcpServers": {
    "pythonTools": {
      "command": "python",
      "args": ["-m", "my_mcp_server", "--port", "8080"],
      "cwd": "./mcp-servers/python",
      "env": {
        "DATABASE_URL": "$DB_CONNECTION_STRING",
        "API_KEY": "${EXTERNAL_API_KEY}"
      },
      "timeout": 15000
    }
  }
}

Node.js MCP 伺服器 (Stdio)

{
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["dist/server.js", "--verbose"],
      "cwd": "./mcp-servers/node",
      "trust": true
    }
  }
}

基於 Docker 的 MCP 伺服器

{
  "mcpServers": {
    "dockerizedServer": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "API_KEY",
        "-v",
        "${PWD}:/workspace",
        "my-mcp-server:latest"
      ],
      "env": {
        "API_KEY": "$EXTERNAL_SERVICE_TOKEN"
      }
    }
  }
}

基於 HTTP 的 MCP 伺服器

{
  "mcpServers": {
    "httpServer": {
      "httpUrl": "http://localhost:3000/mcp",
      "timeout": 5000
    }
  }
}

具有自訂標頭的基於 HTTP 的 MCP 伺服器

{
  "mcpServers": {
    "httpServerWithAuth": {
      "httpUrl": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token",
        "X-Custom-Header": "custom-value",
        "Content-Type": "application/json"
      },
      "timeout": 5000
    }
  }
}

發現過程深入探討

當 Gemini CLI 啟動時，它會透過以下詳細過程執行 MCP 伺服器發現：

1. 伺服器迭代與連線

對於 mcpServers 中的每個設定伺服器：

狀態追蹤開始：伺服器狀態設定為 CONNECTING。
傳輸選擇：根據設定屬性：
- httpUrl → StreamableHTTPClientTransport
- url → SSEClientTransport
- command → StdioClientTransport
建立連線： MCP 客戶端嘗試使用設定的逾時時間進行連線。
錯誤處理：連線失敗會被記錄下來，且伺服器狀態設定為 DISCONNECTED。

2. 工具發現

成功連線後：

工具列表：客戶端呼叫 MCP 伺服器的工具列表端點。
結構驗證：每個工具的函式宣告都會被驗證。
名稱清理：工具名稱會被清理以符合 Gemini API 的要求：
- 無效字元（非字母數字、底線、點、連字號）會被底線取代。
- 超過 63 個字元的名稱會被截斷並在中間替換（___）。

3. 衝突解決

當多個伺服器公開同名工具時：

先註冊者優先：第一個註冊工具名稱的伺服器會獲得未加前綴的名稱。
自動加前綴：後續的伺服器會獲得加前綴的名稱：serverName__toolName。
註冊表追蹤：工具註冊表會維護伺服器名稱與其工具之間的對應關係。

4. 結構處理

工具參數結構會經過清理以符合 Gemini API 的相容性：

$schema 屬性會被移除。
additionalProperties 會被移除。
具有 default 的 anyOf 的預設值會被移除（Vertex AI 相容性）。
遞迴處理 會應用於巢狀結構。

5. 連線管理

發現後：

持續連線：成功註冊工具的伺服器會維持其連線。
清理：未提供任何可用工具的伺服器連線會被關閉。
狀態更新：最終的伺服器狀態會設定為 CONNECTED 或 DISCONNECTED。

工具執行流程

當 Gemini 模型決定使用 MCP 工具時，會發生以下執行流程：

1. 工具叫用

模型會產生一個 FunctionCall，其中包含：

工具名稱：已註冊的名稱（可能已加前綴）。
參數：符合工具參數結構的 JSON 物件。

2. 確認過程

每個 DiscoveredMCPTool 都會實作精密的確認邏輯：

基於信任的繞過

if (this.trust) {
  return false; // 不需要確認
}

動態允許清單

系統會維護內部允許清單：

伺服器層級： serverName → 此伺服器的所有工具都受信任。
工具層級： serverName.toolName → 此特定工具受信任。

使用者選擇處理

需要確認時，使用者可以選擇：

僅執行一次：僅此次執行。
永遠允許此工具：新增至工具層級允許清單。
永遠允許此伺服器：新增至伺服器層級允許清單。
取消：中止執行。

3. 執行

確認後（或信任繞過）：

參數準備：參數會根據工具的結構進行驗證。
MCP 呼叫：底層的 CallableTool 會使用以下方式叫用伺服器：

const functionCalls = [
  {
    name: this.serverToolName, // 原始伺服器工具名稱
    args: params,
  },
];

回應處理：結果會被格式化，供 LLM 上下文和使用者顯示。

4. 回應處理

執行結果包含：

llmContent: 供語言模型上下文使用的原始回應部分。
returnDisplay: 供使用者顯示的格式化輸出（通常是 markdown 程式碼區塊中的 JSON）。

如何與您的 MCP 伺服器互動

使用 `/mcp` 指令

/mcp 指令提供有關您 MCP 伺服器設定的完整資訊：

/mcp

這會顯示：

伺服器列表：所有已設定的 MCP 伺服器。
連線狀態： CONNECTED、CONNECTING 或 DISCONNECTED。
伺服器詳細資料：設定摘要（不包括敏感資料）。
可用工具：每個伺服器的工具列表及其描述。
發現狀態：整體發現過程的狀態。

`/mcp` 輸出範例

MCP Servers Status:

📡 pythonTools (CONNECTED)
  Command: python -m my_mcp_server --port 8080
  Working Directory: ./mcp-servers/python
  Timeout: 15000ms
  Tools: calculate_sum, file_analyzer, data_processor

🔌 nodeServer (DISCONNECTED)
  Command: node dist/server.js --verbose
  Error: Connection refused

🐳 dockerizedServer (CONNECTED)
  Command: docker run -i --rm -e API_KEY my-mcp-server:latest
  Tools: docker__deploy, docker__status

Discovery State: COMPLETED