skip to content

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?

level: middleimportance: nice to knowfreq 5%

answer

  1. one repo versus many repos
  2. gemini mcp add writes project scope
  3. gemini-extension.json bundles more
  4. same name: settings.json wins
  5. no trust option in extensions

basics

~20 s

Use 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
json
{
  "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

for a junior

Know that MCP servers go under mcpServers in settings.json and that gemini mcp add writes that entry for you.

for a middle

Explain user versus project scope, the default project scope of gemini mcp add, trust and includeTools, and what a gemini-extension.json can bundle.

for a senior

Diagnose a missing server: project scope not committed, an untrusted folder, a redacted token, or a same-named settings.json entry shadowing the extension.

for a principal

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.