使用 Gemini CLI 的 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 (string[]): Stdio 传输方式的命令行参数
env (object): 服务器进程的环境变量。值可以使用 $VAR_NAME 或 ${VAR_NAME} 语法引用环境变量
cwd (string): Stdio 传输方式的工作目录
timeout (number): 请求超时时间（毫秒，默认：600,000ms = 10 分钟）
trust (boolean): 当为 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
    }
  }
}

发现流程深度解析

当 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 服务器状态：

📡 pythonTools (已连接)
  命令：python -m my_mcp_server --port 8080
  工作目录：./mcp-servers/python
  超时：15000毫秒
  工具：calculate_sum, file_analyzer, data_processor

🔌 nodeServer (已断开)
  命令：node dist/server.js --verbose
  错误：连接被拒绝

🐳 dockerizedServer (已连接)
  命令：docker run -i --rm -e API_KEY my-mcp-server:latest
  工具：docker__deploy, docker__status

发现状态：已完成