# Gemini CLI: Add MCP Servers and Install Extensions

> Wire an MCP server into Gemini CLI's settings.json or add it with one command, check it with /mcp, and install a packaged extension.

- Canonical: https://guides-ai.pages.dev/guides/gemini-cli-mcp-and-extensions/
- Plate 14.05 · Topic: Other coding agents (https://guides-ai.pages.dev/topics/agents/)
- Published: 06 Sept 2026 · 4 min read
- Source site: guides-ai — https://guides-ai.pages.dev/

Gemini CLI reads MCP servers from `settings.json`, in two places: `~/.gemini/settings.json`
for every project, and `.gemini/settings.json` inside a project for that repo only.

## 1. Add a server by hand

```json
{
  "mcpServers": {
    "local-tools": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "cwd": "./tools",
      "env": { "API_KEY": "$MY_API_TOKEN" },
      "timeout": 30000,
      "excludeTools": ["delete_record"]
    }
  }
}
```

What it does: launches a stdio server from `./tools`, expands `$MY_API_TOKEN` from your
environment so no secret lands in the file, gives it a 30-second request timeout (the
default is 600000 ms), and blocks one tool. `includeTools` is the opposite — an allowlist —
and `excludeTools` wins when both are present.

Each entry needs exactly one of three keys: `command` for stdio, `httpUrl` for a streamable
HTTP endpoint, or `url` for SSE. Remote entries also take `headers`.

## 2. Or add it with one command

```bash
gemini mcp add --transport http company-api https://api.example.com/mcp \
  --header "Authorization: Bearer $TOKEN"
```

What it does: writes the entry for you. `-t` is short for `--transport` and accepts
`stdio` (default), `sse` or `http`; `-H` is short for `--header`; `-e KEY=value` sets an env
var. Scope is `--scope project` by default — pass `--scope user` to make it global.

## 3. Check it

```text
/mcp
```

What it does: shows every configured server, whether it connected, and the tools and prompts
it exposes. `/mcp list` gives the short status view, `/mcp auth` handles OAuth for servers
that need a browser login, and `/mcp enable <name>` / `/mcp disable <name>` toggle one
without editing the file.

## 4. Install an extension

Extensions package prompts, MCP servers, custom commands and sub-agents as one installable
unit:

```bash
gemini extensions install https://github.com/gemini-cli-extensions/workspace
```

What it does: clones the extension into `.gemini/extensions/<name>/`, where its
`gemini-extension.json` manifest declares its `mcpServers` and tool filters. `gemini
extensions list` confirms it installed and is enabled. Other install sources exist — run
`gemini extensions --help` for the current flags rather than guessing.

Note that the `trust: true` option on a server skips confirmation prompts for its tool
calls. Set it only for servers you control.

---

Next: [first steps with Gemini CLI](/guides/gemini-cli-first-steps/) or
[build your own MCP server in Python](/guides/build-mcp-server-python/).