Setup Patterns & Authentication

MCP server configuration in Gemini CLI follows a layered resolution model. Global settings in ~/.gemini/settings.json apply to every project. Project-level settings in .gemini/settings.json override globals for that specific codebase. This separation matters because some servers — memory, GitHub, general-purpose fetch — belong in your global config. Others — project-specific databases, internal API servers, custom tooling — belong in the project config and should be checked into version control.

Authentication for MCP servers splits into three patterns. Environment variable injection uses the env block in settings.json with ${VAR} references — the server process inherits the value from your shell. OAuth-based servers like Google Drive or Slack MCP servers handle their own auth flow on first connection, storing tokens in the server's data directory. API key servers expect a key passed as an argument or environment variable. The critical rule: never hardcode credentials in settings.json. Every secret flows through environment variables.

Gemini CLI's settings.json supports a timeout field per server, measured in milliseconds. Servers that fail to initialize within the timeout are marked as unavailable for the session. The default is generous — 30 seconds — but custom servers connecting to slow external services may need more. Conversely, local-only servers like memory or filesystem should initialize in under 2 seconds. Set aggressive timeouts for local servers to fail fast when something is wrong.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      },
      "timeout": 15000,
      "includeTools": ["create_pull_request", "list_issues", "search_code"]
    },
    "internal-api": {
      "command": "node",
      "args": ["./tools/mcp-internal-api/index.js"],
      "env": {
        "API_BASE_URL": "${INTERNAL_API_URL}",
        "API_KEY": "${INTERNAL_API_KEY}"
      },
      "timeout": 10000
    }
  }
}