Gemini CLI 0.21.0：MCP 服务器配置的统一化改进

Gemini CLI 0.21.0 是对 MCP (Model Context Protocol) 服务器配置方式的统一化处理，解决了之前与标准不一致的问题。

问题背景

在 0.21.0 之前，Gemini CLI 在配置远程 MCP 服务器时采用了一种独特的方式：需要根据传输协议的不同，分别使用 httpUrl 或 url 字段。这种设计与业界其他服务（如 Sentry、Notion）的做法不一致。

这种不一致带来的实际问题是：当从其他 MCP 服务器文档中复制配置示例并粘贴到 Gemini CLI 的 settings.json 文件时，配置往往无法直接工作。需要手动修改字段名称，将统一的 url 字段改为 httpUrl 或保持 url，具体取决于服务端使用的传输协议。

正如相关 PR #13762 中提到的：“copying directly into your Gemini CLI settings.json file fails because we have gone our own route.”

统一配置方式

Gemini CLI 0.21.0 版本将远程 MCP 服务器的配置统一为使用单一的 url 参数，通过可选的 type 参数来明确指定传输方式。这一改进既简化了配置过程，又与行业标准保持了一致。

配置文件位置

MCP 服务器的配置位于 ~/.gemini/settings.json 文件中，所有服务器都定义在 mcpServers 对象下。

新旧配置对比

旧方式（仍然支持，保持向后兼容）：

{
  "mcpServers": {
    "my-sse-server": {
      "url": "https://api.example.com/sse"
    },
    "my-http-server": {
      "httpUrl": "https://api.example.com/mcp"
    }
  }
}

新方式（统一使用 url 字段）：

{
  "mcpServers": {
    "my-sse-server": {
      "url": "https://api.example.com/sse",
      "type": "sse"
    },
    "my-http-server": {
      "url": "https://api.example.com/mcp",
      "type": "http"
    }
  }
}

更简洁的方式是省略 type 参数，让 Gemini CLI 自动检测：

{
  "mcpServers": {
    "my-server": {
      "url": "https://api.example.com/sse"
    }
  }
}

三种传输方式

Gemini CLI 支持三种 MCP 传输机制，每种都有其适用场景：

1. 本地进程传输 (Stdio)

这种方式通过标准输入输出与本地进程通信，适用于本地 MCP 服务器：

{
  "mcpServers": {
    "python-server": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "env": {
        "API_KEY": "$EXTERNAL_API_KEY"
      }
    },
    "nodejs-server": {
      "command": "node",
      "args": ["dist/server.js"],
      "trust": true
    }
  }
}

2. SSE 传输 (Server-Sent Events)

适用于需要服务器主动推送更新的场景：

{
  "mcpServers": {
    "remote-sse": {
      "url": "https://api.example.com/sse",
      "type": "sse",
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  }
}

3. HTTP 流式传输

使用标准 HTTP 协议进行通信：

{
  "mcpServers": {
    "remote-http": {
      "url": "https://api.example.com/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  }
}

自动传输检测机制

当省略 type 参数时，Gemini CLI 会实现智能的传输协议检测：

1. 首先尝试使用 HTTP 传输连接
2. 如果 HTTP 连接失败，自动回退到 SSE 传输
3. 在回退过程中会自动检测 401 认证错误
4. 如果已有存储的 OAuth 令牌，会在 SSE 回退时自动使用

这种自动检测机制让配置变得更加简单，无需提前了解服务器使用的具体传输协议。

可选配置参数

无论使用哪种传输方式，以下可选参数都可以使用：

• headers (object): 为远程连接添加自定义 HTTP 头
• timeout (number): 请求超时时间（毫秒），默认 600,000ms
• trust (boolean): 设为 true 时跳过工具确认，默认为 false
• includeTools (string[]): 白名单，只允许特定名称的工具
• excludeTools (string[]): 黑名单，排除特定工具（优先级高于 includeTools）
• authProviderType: 认证提供者类型，可选值包括：
  • dynamic_discovery (默认): 自动发现 OAuth 配置
  • google_credentials: 使用 Google 应用默认凭据
  • service_account_impersonation: 服务账号模拟

服务账号模拟示例

对于受 Identity-Aware Proxy (IAP) 保护的资源：

{
  "mcpServers": {
    "protected-service": {
      "url": "https://my-service.run.app/mcp",
      "authProviderType": "service_account_impersonation",
      "targetAudience": "oauth-client-id",
      "targetServiceAccount": "[email protected]"
    }
  }
}

OAuth 认证的改进

0.21.0 版本对 OAuth 认证流程也进行了优化：

自动认证处理

• 自动检测 401 响应，判断是否需要 OAuth 认证
• 在浏览器中打开认证流程
• 将令牌安全存储在 ~/.gemini/mcp-oauth-tokens.json
• 自动管理令牌刷新

更友好的错误提示

• 认证错误现在以信息提示的形式展示，而不是"吓人的错误信息"
• 更清晰地区分传输失败和认证失败

手动认证控制

OAuth 认证流程不再在 CLI 启动时自动触发，可以通过 /mcp auth 命令来：

• 查看已配置和自动检测到的 OAuth 服务器列表
• 手动触发认证流程
• 管理已存储的认证令牌

全局服务器控制

通过 mcp 对象可以全局控制服务器的发现和连接：

{
  "mcp": {
    "allowed": ["server1", "server2"],
    "excluded": ["server3"]
  }
}

• mcp.allowed: 白名单，只连接列出的服务器
• mcp.excluded: 黑名单，跳过列出的服务器

CLI 命令管理

Gemini CLI 提供了一套完整的命令来管理 MCP 服务器：

• gemini mcp add: 注册新服务器
• gemini mcp list: 显示已连接的服务器和可用工具
• gemini mcp remove: 取消注册服务器
• /mcp auth: 管理 OAuth 认证

其他改进

除了配置统一化，gemini 0.21.0 版本还包含了一些其他 MCP 相关改进：

支持 MCP Resources

MCP Resources 功能让服务器可以提供额外的资源定义，这些资源会被自动发现并集成到对话中。

无参数提示符自动执行

当 MCP 提示符不需要任何参数时，按下回车键会自动执行该提示符，减少了额外的确认步骤。

传输类型别名

添加了 --type 作为 --transport 的别名，使命令行参数更加简洁和直观。

参考

• https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md
• Gemini CLI PR #13762
• Gemini CLI 扩展浏览器