Gemini CLI Setup: GEMINI.md Context, MCP Servers, Extensions

Context files, named GEMINI.md by default, hold instructions you would otherwise repeat in every prompt: conventions, commands, persona, style. The CLI loads them hierarchically, concatenates all of them, and sends the result with every prompt:

1. Global: ~/.gemini/GEMINI.md, default instructions for every project.
2. Workspace: GEMINI.md files in your configured workspace directories and their parent directories.
3. Just-in-time: when a tool accesses a file or directory, the CLI scans that directory and its ancestors, up to a trusted root, for GEMINI.md files, so component-specific instructions load only when needed.

The footer shows how many context files are loaded. /memory show prints the full concatenated context, which is the fastest way to see what the model is actually told, and /memory reload rescans after you edit files.

Large context files can be split with imports: a line such as @./components/instructions.md inside GEMINI.md pulls another file in, with relative or absolute paths. If your repository already has an AGENTS.md for other agents, point Gemini CLI at it:

1{2  "context": {3    "fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]4  }5}

Inside a prompt, @path shares a file or directory with the model, for example @src/auth/session.ts explain the token refresh. To keep paths out of that and other tools, add a .geminiignore file at the project root. It follows .gitignore conventions: # comments, globs (*, ?, []), a trailing / for directories, a leading / to anchor to the file's location, and ! to negate:

1# keep generated and secret files out2/dist/3apikeys.txt4*.md5!README.md

Two limits from the docs are worth knowing. Paths in .geminiignore are excluded from tools that respect it, such as @ references; they are still visible to other services, so it is not an access control. And changes take effect only after you restart the session.

Gemini CLI connects to MCP servers listed under mcpServers in settings.json: the user file ~/.gemini/settings.json or the project file .gemini/settings.json. Each server needs one of command (stdio), url (SSE), or httpUrl (streamable HTTP):

1{2  "mcpServers": {3    "github": {4      "command": "npx",5      "args": ["-y", "@modelcontextprotocol/server-github"],6      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN" },7      "timeout": 30000,8      "trust": false,9      "includeTools": ["get_issue", "list_pull_requests"]10    },11    "docs-search": {12      "httpUrl": "https://mcp.example.com/mcp/",13      "headers": { "Authorization": "Bearer $DOCS_TOKEN" }14    }15  }16}

Or add them from the terminal, which writes the same settings (user or project scope with -s):

1gemini mcp add -e API_KEY=123 my-stdio-server /path/to/server arg12gemini mcp add --transport http docs-search https://mcp.example.com/mcp/

In a session, /mcp lists connected servers with their tools, prompts, and resources. Discovered tools get fully qualified names in the form mcp_{serverName}_{toolName}.

An MCP server is third-party code with access to whatever you give it. Gemini CLI provides several controls:

• Tool filtering. includeTools is an allowlist for a server's tools; excludeTools removes tools and wins if a tool is in both. Expose only the tools a task needs.
• Server allow and deny lists. The global mcp.allowed and mcp.excluded settings decide which configured servers connect at all.
• Confirmations. trust defaults to false, so tool calls ask for confirmation. Setting trust: true bypasses all confirmations for that server; reserve it for servers you wrote.
• Environment redaction. When spawning servers, the CLI redacts sensitive variables inherited from your shell, such as GEMINI_API_KEY, GOOGLE_API_KEY, and anything matching *TOKEN*, *SECRET*, *PASSWORD*, *KEY*, *AUTH*, or *CREDENTIAL*. A server receives a secret only if you list it explicitly in its env.

One naming rule matters for policies: do not use underscores in server names. The policy parser splits fully qualified names on the first underscore after mcp_, so my_server breaks wildcard rules silently; use my-server.

An extension bundles prompts (a context file), MCP servers, custom commands, themes, hooks, sub-agents, and agent skills into one installable unit. Install and manage them from the terminal:

1gemini extensions install https://github.com/gemini-cli-extensions/workspace2gemini extensions list3gemini extensions update4gemini extensions new ./my-extension mcp-server   # start from a template5gemini extensions link ./my-extension             # develop without reinstalling

Installation copies the extension into ~/.gemini/extensions; gemini extensions update pulls changes. Management commands are not available inside interactive sessions (use /extensions list there), and changes apply after you restart the CLI.

Each extension has a gemini-extension.json manifest at its root:

1{2  "name": "my-extension",3  "version": "1.0.0",4  "description": "Internal service tools",5  "mcpServers": {6    "my-server": {7      "command": "node",8      "args": ["${extensionPath}/my-server.js"],9      "cwd": "${extensionPath}"10    }11  },12  "contextFileName": "GEMINI.md",13  "excludeTools": ["run_shell_command(rm -rf)"]14}

Use ${extensionPath} for portability, split executables and arguments into command and args, and keep name lowercase with dashes, matching the directory name. Extension MCP servers support every option except trust, and a server with the same name in your settings.json takes precedence.

1. In a repository, write a short GEMINI.md with your test command and two conventions. Start gemini and run /memory show to confirm it loaded.
2. Add a .geminiignore with /dist/, restart, and confirm @dist/ no longer shares files.
3. Run gemini mcp add for one MCP server you trust, with includeTools limited to two tools in settings.json, and check /mcp.
4. Ask a question that needs one of those tools and approve the confirmation.
5. Scaffold an extension with gemini extensions new ./my-ext context, add a GEMINI.md to it, gemini extensions link ./my-ext, restart, and confirm its context appears in /memory show.

Pass criterion: you can show the concatenated context, the filtered tool list for your server, and the linked extension's context, and explain which of them is sent with every prompt.