# How to add an MCP server to Gemini CLI

Level 3: Connect AI to your tools · 6 min · Updated 19 November 2026 · Path: Connect MCP servers to your assistant

By the end you'll add local and remote MCP servers to Gemini CLI, limit which tools it may use, and check that they connect.

Gemini CLI reads [MCP](https://ai-powered.com/academy/glossary/mcp) servers from a `settings.json` file, and gives you a command to write it for you. One thing to check first: as of 19 November 2026, the Gemini CLI docs carry a notice that Gemini CLI was replaced by Antigravity CLI for unpaid-tier and Google One users on 18 June 2026. If that's you, see the [Antigravity lesson](https://ai-powered.com/academy/connect-mcp-servers/antigravity) instead.

## Add a server with a command

```shell
# a local (stdio) server, with keys
gemini mcp add -e API_KEY=123 my-stdio-server /path/to/server arg1 arg2

# a remote server over Streamable HTTP
gemini mcp add --transport http http-server https://api.example.com/mcp/

# with an auth header
gemini mcp add --transport http --header "Authorization: Bearer abc123" secure-http https://api.example.com/mcp/
```

The command writes to the project's `.gemini/settings.json` by default; use `-s user` for `~/.gemini/settings.json` so the server works everywhere.

## Or edit settings.json

Each server needs exactly one of `command` (local), `url` (SSE) or `httpUrl` (Streamable HTTP):

```json
{
  "mcpServers": {
    "httpServerWithAuth": {
      "httpUrl": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer $MY_API_TOKEN"
      }
    }
  }
}
```

Values in `env` and headers can reference shell variables such as `$MY_API_TOKEN`, so keys stay out of the file.

## Limit what it can do

- `includeTools` lists the only tools the model may see; `excludeTools` hides tools (and wins over `includeTools`).
- `trust: true` skips tool-call confirmations for that server. The docs advise it only for servers you fully control.
- Avoid underscores in server names (`my-server`, not `my_server`): the docs warn that policy rules split tool names on underscores and can fail silently.

**Watch out**

Leave `trust` off for any server you didn't write. Confirmations are how you catch a [tool call](https://ai-powered.com/academy/glossary/tool-call) you didn't expect.

## Check that it worked

Run `gemini mcp list` in a shell, or `/mcp` inside a session to see each server's status (CONNECTED, CONNECTING or DISCONNECTED) and its tools.

## Servers developers use

MCP servers for developer tools from the directory:

- [GitHub](https://ai-powered.com/mcp/github-2): Official MCP server connecting AI assistants to GitHub repos, issues and workflows
- [fastmcp](https://ai-powered.com/mcp/fastmcp): Python framework for building MCP servers, clients and interactive apps
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Local MCP server that builds a code knowledge graph for AI coding agents
- [XERJ](https://ai-powered.com/mcp/xerj): Local search engine for AI agents with cited answers over your code and docs
- [REA](https://ai-powered.com/mcp/rea): CLI and MCP server that lets coding agents reverse engineer apps and binaries

## Key takeaways

- `gemini mcp add` writes `settings.json`; project scope by default, `-s user` for everywhere.
- One of `command`, `url` or `httpUrl` per server.
- Narrow tools with `includeTools`/`excludeTools`; keep `trust` off.

## What to try next

- On the free tier? The same servers work in [Antigravity](https://ai-powered.com/academy/connect-mcp-servers/antigravity), with a different file.
- Vet a server first: [Is this MCP server safe?](https://ai-powered.com/academy/connect-mcp-servers/is-this-mcp-server-safe)

## Sources

Official documentation, checked on 19 November 2026:

- [MCP servers with Gemini CLI (Gemini CLI docs)](https://geminicli.com/docs/tools/mcp-server/)

Next lesson: [How to add an MCP server to Antigravity](https://ai-powered.com/academy/connect-mcp-servers/antigravity)
