Gemini CLI MCP Servers: How to Add and Configure Them

Gemini CLI is useful the moment you install it. It gets far more useful once it can reach your issue tracker, your database, or a folder of design files without you pasting anything into the prompt. The bridge is the Model Context Protocol, and each bridge is an MCP server. Gemini CLI can talk to servers that run as local processes, to servers behind a plain HTTP endpoint, and to older streaming SSE endpoints. It gives you two ways to register them: one gemini mcp add command, or a few lines in settings.json.

This article walks through both routes with real commands, then deals with the parts that usually go wrong: scopes, secrets, tool filtering, OAuth, and the dreaded Disconnected status. Every flag and field below comes from the official Gemini CLI MCP documentation, and where behavior differs between releases, I say so.

💡 Quick answer: run gemini mcp add -s user <name> <command-or-url>, then type /mcp inside the CLI. The server should show as connected and list its tools.

What MCP Servers Add to Gemini CLI

At startup, Gemini CLI reads your configured servers, connects to each one, and asks what it offers. The server answers with a list of tools, and each tool has a name, a description, and a JSON schema for its inputs. The model sees those tools next to the built-in ones (file reads, shell commands, web search) and calls them when a prompt needs them.

Tools, Prompts, and Resources

A server can expose three kinds of things:

• Tools are actions: query a table, open an issue, resize an image.
• Prompts are reusable templates that can show up as slash commands.
• Resources are readable data such as files or records.

Most servers ship tools only, and tools are where your configuration effort pays off. Everything below is about getting those tools connected safely.

Pick a Transport

Every server entry uses exactly one of three transports. The field you set decides which one the CLI uses.

With stdio, the CLI starts the process and talks to it over standard input and output. That means a server must never print stray text to stdout. Logs belong on stderr, or the protocol stream breaks and the server drops out.

The choice is usually made for you. If a server is a package or a script on your machine, use stdio. If it lives at a URL and the vendor offers both HTTP and SSE, pick HTTP, since SSE is the older transport and exists mostly for servers that have not moved yet.

Add a Server With One Command

If gemini is not on your PATH yet, install it with npm install -g @google/gemini-cli. After that, the add command is the fastest route.

The gemini mcp add Syntax

gemini mcp add [options] <name> <commandOrUrl> [args...]

Copy Prompt

The name comes first, then the executable or URL, then any arguments the server needs. The options you will use most:

Local Stdio and Remote Examples

A local script, saved for your user so it works in every folder:

gemini mcp add -s user -e ISSUES_TOKEN='$ISSUES_TOKEN' issues node /home/me/mcp/issues-server.js

Copy Prompt

A hosted server over streamable HTTP, with a bearer header:

gemini mcp add --transport http --header "Authorization: Bearer abc123" docs-search https://mcp.example.com/mcp

Copy Prompt

An older SSE endpoint:

gemini mcp add --transport sse legacy-events http://localhost:8080/sse

Copy Prompt

Day-to-day management uses the same command family:

gemini mcp list
gemini mcp disable issues --session
gemini mcp enable issues
gemini mcp remove issues -s user

Copy Prompt

The --session flag on enable and disable changes the state for the current session only. Without it, the choice is saved to ~/.gemini/mcp-server-enablement.json.

💡 Mind your quotes. In the first example, the single quotes keep $ISSUES_TOKEN as a placeholder. With double quotes, your shell expands it first and the real token lands in settings.json. Open the file after adding a server and check.

💡 Arguments that start with a dash, such as npx -y, can be mistaken for CLI options by the flag parser. For servers launched that way, write the entry in settings.json instead.

Edit settings.json by Hand

The add command writes JSON for you. Editing that JSON directly gives you every field, keeps your setup reviewable in a pull request, and makes it easy to copy a working block to a colleague.

User Scope or Project Scope

• User scope: ~/.gemini/settings.json. It follows you into every folder.
• Project scope: .gemini/settings.json inside the repository. Commit it and the whole team gets the same servers.

The project file is read after the user file, so it wins when both define the same server name. Remember that gemini mcp add writes to project scope unless you pass -s user.

A Working Multi-Server File

This file registers one server per transport:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/projects"],
      "timeout": 30000
    },
    "issues": {
      "command": "node",
      "args": ["./mcp/issues-server.js"],
      "cwd": "/home/me/work/tracker",
      "env": { "ISSUES_TOKEN": "$ISSUES_TOKEN" },
      "includeTools": ["search_issues", "get_issue"]
    },
    "docs-search": {
      "httpUrl": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer abc123" },
      "timeout": 15000
    },
    "legacy-events": {
      "url": "http://localhost:8080/sse"
    }
  }
}

Copy Prompt

Here is what each field does:

Keep Secrets Out of the File

Inside the env block, Gemini CLI expands $NAME and ${NAME} on every platform, and %NAME% on Windows. A variable that is not set becomes an empty string, with no warning. The result is a server that starts, then fails authentication, which looks like a bug in the server when it is really a typo in a variable name.

A project file is usually committed, so reference variables and never paste a secret into it. Expansion is documented for the env block, so if you want a token in headers, confirm your CLI version expands it, or keep that entry in user scope where it never reaches version control.

Limit Access and Handle Auth

Connecting a server hands the model a new set of abilities. Decide how much of that you want before the first prompt.

Filter Tools Per Server

Say a server exposes search_issues, get_issue, and delete_issue. You want the first two and never the third:

"issues": {
  "command": "node",
  "args": ["./mcp/issues-server.js"],
  "includeTools": ["search_issues", "get_issue"],
  "excludeTools": ["delete_issue"]
}

Copy Prompt

excludeTools takes precedence, so a tool listed in both is off. You can also filter whole servers from the top level of settings.json:

"mcp": {
  "allowed": ["issues", "filesystem"],
  "excluded": ["experimental-server"]
}

Copy Prompt

When mcp.allowed is set, only the servers named there connect. mcp.excluded blocks the ones you list.

Use Trust Sparingly

By default, Gemini CLI asks before it runs a tool. Setting "trust": true, or passing --trust when you add a server, turns off every confirmation for that server. That is reasonable for a read-only server you wrote yourself. It is a bad idea for anything that can write files, send messages, or run commands, because one bad prompt could trigger it without you seeing it first.

OAuth With /mcp auth

Many hosted servers need you to log in. Inside the CLI, run /mcp auth to list the servers that support OAuth, then authenticate one by name:

/mcp auth docs-search

Copy Prompt

The CLI opens your browser, finishes the flow, and stores the token in ~/.gemini/mcp-oauth-tokens.json. Expired tokens are refreshed automatically. When a server does not publish its OAuth details, add an oauth block yourself:

"oauth": {
  "enabled": true,
  "clientId": "gemini-cli-client",
  "authorizationUrl": "https://auth.example.com/oauth/authorize",
  "tokenUrl": "https://auth.example.com/oauth/token",
  "scopes": ["mcp:read"]
}

Copy Prompt

Static Headers and Google Credentials

Not every server uses OAuth. A fixed bearer token goes in headers, as shown earlier. For services on Google Cloud, the authProviderType field accepts google_credentials, plus service_account_impersonation together with targetServiceAccount. For servers behind Identity-Aware Proxy, add targetAudience with the OAuth client ID. The default provider works for most other servers, so leave the field alone unless you need one of these.

Check That Everything Works

Edit the file, then run /mcp reload. If the CLI still shows the old settings afterwards, restart the session.

Verify With /mcp Commands

Outside a session, gemini mcp list gives you the same connection overview from the shell.

How Tool Names Appear

Recent releases show MCP tools with a fully qualified name shaped like mcp_<server>_<tool>. A search_issues tool on a server called issues becomes mcp_issues_search_issues. Older write-ups describe a server__tool prefix, used when two servers expose a tool with the same name. If you see one style in a tutorial and the other on your screen, you are most likely on a different version.

Two practical consequences follow. First, name your servers with hyphens, not underscores. The name is split on the first underscore after mcp_, and an underscore inside a server name can confuse policy rules. Second, you rarely need the full name in a prompt. Ask in plain language, for example:

Use the issues server to list open bugs labelled regression, newest first.

Copy Prompt

The CLI shows which tool it plans to call and asks for confirmation unless you set trust.

Fix Servers That Won't Connect

Start with the boring checks, because they solve most cases:

1. Run the exact command and args in a normal terminal. If it fails there, it fails in the CLI.
2. Confirm cwd exists and that node, npx, or python3 is on your PATH.
3. Start the CLI with --debug and read the connection errors.
4. Check the server's stderr for stack traces.
5. Run /mcp reload after every edit, and restart the CLI if the old settings seem to stick.

Disconnected in Untrusted Folders

This one catches people constantly. In a folder you have not trusted, Gemini CLI does not connect to any MCP server, and it ignores the project's .gemini/settings.json entirely. Your user-scope file is read, but project servers simply do not appear.

Run /permissions inside the CLI to trust the folder, or answer the trust dialog the first time you open it. The choice is saved in ~/.gemini/trustedFolders.json. For headless runs, the docs list the --skip-trust flag and the GEMINI_CLI_TRUST_WORKSPACE=true variable.

Timeouts and Silent Failures

Some failures give no error at all:

• No tools listed: the server connected but registered nothing, or its tool schemas are invalid JSON Schema. Check /mcp schema.
• Tool calls hang: the default timeout is ten minutes. Lower timeout for flaky remote servers, or raise it for slow jobs such as large queries.
• Authentication errors after a clean start: look for an unset variable in env. It expanded to an empty string.
• Tool missing from the list: check includeTools and excludeTools, and the mcp.allowed list at the top level.

💡 A fast sanity test: add a tiny stdio server first, get it connected, and only then add the remote servers. Each new server is one more thing that can fail, so add them one at a time.

Draft Configs With Gemini on Picasso IA

You can use a language model to draft the boring parts of a config, and Picasso IA hosts several Gemini models you can open in the browser. Here is a workflow that works well:

1. Open the Gemini 3.5 Flash page for quick drafts. For long files with several servers or tricky auth, try Gemini 3.1 Pro. Gemini 3 Flash is another option for fast iteration.
2. Paste the setup section from the MCP server's README, then add your constraints: operating system, scope, and which environment variable holds the token.
3. Ask for two outputs: the settings.json entry and the equivalent gemini mcp add command. Tell the model to use $VARIABLE references instead of literal secrets.
4. Check the answer against the field table above. Exactly one of command, url, or httpUrl should be present, and every name in includeTools should match what /mcp desc prints.
5. Paste the entry into your file and run /mcp reload.

💡 Treat the draft as a first pass. A model can invent a field that sounds right. The tables in this article and the official docs are your source of truth.

Create Your Own Images on Picasso IA

A good MCP setup is only half of a clean developer workflow. The other half is the material around it: README banners, tutorial illustrations, social cards, and photos for the blog post that explains your setup.

Picasso IA lets you generate those images in a few minutes. Try Seedream 4.5 for detailed photoreal scenes, GPT Image 2 when you need clean text inside an image, or Nano Banana 2 Lite for quick drafts. Write a short prompt, generate a few variations, and keep the one that fits your page.

Pick a project you have open today, write one prompt describing its banner, and see what comes back. Browse every available model at picassoia.com/en/all-models, and start with whichever one matches the look you have in mind.