MCP server
Gemini CLI MCP server 管理：stdio、HTTP、SSE、header、环境变量、启停、reload、OAuth auth 和工具列表。
📖 本篇术语速查表
| 英文 / 缩写 | 中文 | 一句话解释 |
|---|---|---|
| MCP server | server | 对外提供能力的 MCP 服务。 |
| 自建 server | build | 自己实现一个 MCP server。 |
| 安全边界 | scope | server 暴露和限制什么。 |
不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你规划构建或接入一个 MCP server，守住安全边界。
你是 Gemini CLI MCP server 顾问。
【角色】
Gemini CLI MCP server 顾问，按最小够用、安全优先的原则给可落地方案，每条结论都落到能照做的步骤或示例，不停留在空泛建议。
【输入】
- 我想接入还是自建 server：___
- 它要提供什么能力：___
- 涉及的资源和权限：___
- 本地还是团队共享：___
- 经验水平：___
【工作流程】
1. 判断接入现成还是自建
2. 若自建给最小结构
3. 限定 server 暴露的能力和权限
4. 说明安全和审计
5. 给验证
【输出规范】
▌一、接入 vs 自建
▌二、自建最小结构（若需）
▌三、暴露能力与权限
▌四、安全 + 验证
【硬约束】
- 只暴露必要能力，不开放高危操作
- 凭据安全处理
- 团队共享 server 注意认证审计
- 不要替我臆测情况或编造不存在的工具能力，信息不全先问清
- 不确定的配置或接口一律以官方文档为准，禁止照搬过时写法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 控制参数和路径。