gemini-cli-mcp-config-format-matrix

Goal

Generate correct Gemini CLI MCP configuration without mixing formats from other clients.

Rules

1. Prefer Gemini-native JSON config in settings.json:
   • top-level mcpServers for server entries.
   • optional top-level mcp for global policies (allowed, excluded, optional serverCommand).
2. For stdio servers, use server entry fields compatible with Gemini CLI:
   • command, optional args, optional cwd, optional timeout, optional trust.
   • Do not generate env for Gemini snippets as a generic tunneling mechanism for host env vars.
3. For streamable HTTP servers, use httpUrl in server entry.
4. For HTTP auth headers, use Gemini-native header mapping:
   • JSON: headers: { "Authorization": "Bearer ..." }
   • CLI: --header "Authorization: Bearer ..."
5. Keep Gemini snippets client-native:
   • Do not emit Codex TOML fields (bearer_token_env_var, http_headers, env_http_headers).
   • Do not emit Claude Desktop MCP format.
6. Preserve secure placeholder values in examples:
   • Prefer placeholders like ${TOKEN_ENV_VAR} in JSON examples instead of hardcoded secrets.
7. When server filtering is required, use Gemini fields:
   • includeTools / excludeTools on the server entry.
8. When generating commands for management operations, use Gemini CLI verbs:
   • gemini mcp add -s user ...
   • gemini mcp list
   • gemini mcp remove <name>
9. Do not generate --env flags for Gemini CLI snippets.

Output Patterns

• Local stdio snippet: JSON mcpServers.<name>.command with optional args and env.
• Remote streamable snippet: JSON mcpServers.<name>.httpUrl with optional headers.

JSON Examples (Gemini Docs Aligned)

Use these as canonical formatting references for settings.json.

Stdio server with args

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "mcp4openapi", "--profile", "gitlab"]
    }
  }
}

Streamable HTTP server with OAuth (or none) autentization

{
  "mcpServers": {
    "gitlab": {
      "httpUrl": "https://<cmp_server_host>/profile/gitlab/mcp"
    }
  }
}