{ ...文件包含其他配置对象
  "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 传输的命令行参数
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
    }
  }
}

发现过程深入探讨

当 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 被剥离
anyOf 与 default 的默认值被删除（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

发现状态：已完成