In Gemini CLI, when do you declare an MCP server under mcpServers in settings.json, and when do you ship it inside an extension instead?
answer
- one repo versus many repos
- gemini mcp add writes project scope
- gemini-extension.json bundles more
- same name: settings.json wins
- no trust option in extensions
basics
~20 sUse mcpServers in user or project settings.json for a server one person or one repository needs. Package it in an extension when it travels with context, commands or policies across repositories; a same-named settings.json entry wins.
solid answer
~40 s`mcpServers` in `~/.gemini/settings.json` or the project's `.gemini/settings.json` is the direct route: `command` and `args` for a stdio server, `url` or `httpUrl` for a remote one, plus `env`, `timeout`, `trust`, `includeTools` and `excludeTools`; `gemini mcp add` writes it, to project scope unless you pass `-s user`. An **extension** is a directory with a `gemini-extension.json` manifest that can declare the same `mcpServers` (every option except `trust`) alongside a context file, `excludeTools`, custom commands, skills, hooks, policies and `settings` for secrets. It is installed once per user with `gemini extensions install` from a Git URL or a local path and is versioned with `gemini extensions update`. Choose settings for one repository's server; choose an extension when several repositories or teammates need the same bundle. On a name clash the settings.json server wins.
code
json · 22 lines{
"name": "issue-tracker",
"version": "1.2.0",
"description": "Issue tracker tools and team conventions",
"mcpServers": {
"tracker": {
"command": "node",
"args": ["${extensionPath}/dist/server.js"],
"cwd": "${extensionPath}"
}
},
"contextFileName": "GEMINI.md",
"excludeTools": ["run_shell_command(rm -rf)"],
"settings": [
{
"name": "Tracker token",
"description": "API token for the issue tracker",
"envVar": "TRACKER_TOKEN",
"sensitive": true
}
]
}go deeper
Know that MCP servers go under mcpServers in settings.json and that gemini mcp add writes that entry for you.
Explain user versus project scope, the default project scope of gemini mcp add, trust and includeTools, and what a gemini-extension.json can bundle.
Diagnose a missing server: project scope not committed, an untrusted folder, a redacted token, or a same-named settings.json entry shadowing the extension.
Decide when a team's integrations become a versioned extension with pinned refs and update policy rather than settings copied into every repository.
## Two ways to give Gemini CLI a server Gemini CLI connects to **MCP servers** - external processes or endpoints that offer extra tools - from configuration it reads at startup. There are two places that configuration can live, and they solve different problems. (How the protocol itself works is a separate subject; this is about where Gemini CLI reads the server definition.) ## `mcpServers` in settings.json The top-level `mcpServers` object maps a server name to its configuration: - `command`, `args`, `env`, `cwd` - a local server over stdio. - `url` (SSE, or Streamable HTTP with `type: "http"`) or `httpUrl` - a remote server, with optional `headers`. - `timeout` - request timeout in milliseconds (the MCP page gives 600,000 as the default). - `trust` - `true` skips every tool-call confirmation for that server; the default is `false`. - `includeTools` / `excludeTools` - an allowlist or blocklist of the server's tools; `excludeTools` wins when a tool is in both. It can sit in the user file `~/.gemini/settings.json` or in the project's `.gemini/settings.json`. `gemini mcp add <name> <commandOrUrl>` writes the entry for you; its `--scope` defaults to `project` and its `--transport` to `stdio`, so a bare `gemini mcp add` ends up in the repository's settings file unless you add `-s user`. Global switches `mcp.allowed` and `mcp.excluded` (and `--allowed-mcp-server-names`) restrict which named servers connect at all. Two behaviours catch people out. Gemini CLI **redacts** sensitive variables from the environment it passes to servers - names matching patterns such as `*TOKEN*`, `*KEY*` or `*SECRET*` - so a server that needs a token must receive it explicitly through `env`, for example `"GITHUB_TOKEN": "$GITHUB_TOKEN"`. And in an **untrusted folder** no MCP server connects at all, so a project-scoped server silently disappears until the folder is trusted. To see where you stand, `gemini mcp list` prints each configured server with its transport and a Connected or Disconnected status (stdio servers are only tested in a trusted folder), and inside a session `/mcp list` shows servers and their tools, `/mcp reload` restarts them after an edit, and `/mcp auth <server-name>` runs the OAuth flow for a server that needs it. ## Extensions: a package around the server An **extension** is a directory, installed under `~/.gemini/extensions`, whose root holds a `gemini-extension.json` manifest. Besides `name`, `version` and `description`, the manifest can declare: | Field or folder | What it adds | |---|---| | `mcpServers` | Servers, with every option except `trust`; `${extensionPath}` points into the extension | | `contextFileName` | A context file loaded with the extension (a `GEMINI.md` in its directory is used if this is absent) | | `excludeTools` | Tools hidden from the model, including command-level patterns like `run_shell_command(rm -rf)` | | `settings` | Values asked for at install time, stored in the extension's `.env` or, when `sensitive`, the system keychain | | `commands/`, `skills/`, `hooks/hooks.json`, `policies/` | Custom slash commands, agent skills, hooks and policy rules | The lifecycle is managed outside the interactive session: 1. `gemini extensions install <git-url-or-path>` copies the extension (`--ref` for a branch or tag, `--auto-update`, `--consent` to skip the prompt). 2. `gemini extensions update <name>` (or `--all`) pulls a new version; the installed copy does not follow the source by itself. 3. `gemini extensions link <path>` symlinks a working copy while you develop one. 4. `gemini extensions disable <name> --scope workspace` turns it off for one project; extensions are enabled globally by default. Changes take effect after the CLI restarts. An extension cannot grant itself permissions: `allow` decisions and yolo settings in its policy files are ignored, and its servers cannot set `trust`. An extension is also limited to the environment variables it declares in `settings`. ## Choosing - One developer trying a server: user `settings.json`. - One repository's own server, shared by everyone who clones it: project `.gemini/settings.json`. - The same server plus conventions, commands or policies across many repositories: an extension in its own Git repository, installed by each developer and upgraded with `gemini extensions update`. If an extension and a settings file define a server with the **same name**, the `settings.json` definition takes precedence, which is also how a team overrides one server of an extension locally.
- A server configured with gemini mcp add works for you but teammates don't have it. Why might that be?Without `-s user`, `gemini mcp add` writes to the project's `.gemini/settings.json`. If that file is not committed, teammates never get it; if it is committed but their folder is untrusted, Gemini CLI ignores project settings and connects no MCP servers. `gemini mcp list` shows what each person actually has.
- Your server needs an API token. Why doesn't it see the one exported in your shell?Gemini CLI redacts sensitive variables, names matching patterns like `*TOKEN*` or `*KEY*`, from the environment it hands to MCP servers. Pass it explicitly in the server's `env` block, for example `"TRACKER_TOKEN": "$TRACKER_TOKEN"`; in an extension, declare it in the manifest's `settings` array.
- An extension's server definition overrides the same name in settings.json.
- gemini mcp add writes to your user settings unless told otherwise.
- An extension can mark its servers trusted to skip confirmations.
- MCP servers inherit every variable exported in your shell.
- An installed extension updates itself whenever its Git source changes.
- Extensions can only add MCP servers, nothing else.
Assumes Gemini CLI 0.62.0: gemini mcp add defaults to project scope and stdio, and extension servers cannot set trust, as that release defines them.