How to add an MCP server to Gemini CLI

TL;DR. Gemini CLI reads MCP servers from the mcpServers block of its settings.json (user level at ~/.gemini/settings.json, project level at .gemini/settings.json). For a remote server use httpUrl, or skip the file and run gemini mcp add --transport http <name> <url>. Inside a session, /mcp shows what loaded and /mcp auth <name> signs you in to OAuth servers. Syntax checked against Google's Gemini CLI documentation as of August 2026.

What an MCP server is in Gemini CLI

Gemini CLI is Google's open-source agent for the terminal. On its own it can read and edit files, run shell commands and search the web. An MCP server (Model Context Protocol) adds tools from outside that box: a database, an API, a deployment target. Gemini CLI connects to the server at startup, asks which tools it offers, and from then on the model can call them mid-session, asking you for confirmation first. MCP is an open standard, so one server works the same from Gemini CLI, Claude, Cursor or Codex. If the protocol itself is new to you, what is MCP covers it in a few minutes.

Two ways to add an MCP server to Gemini CLI

Both end in the same place: an entry under mcpServers in a settings.json file. Use whichever you prefer.

1. The gemini mcp add command

As of August 2026 the form is gemini mcp add [options] <name> <commandOrUrl> [args...]. The transport defaults to stdio (a local process), so for a remote server you must say so:

gemini mcp add --transport http hatchable https://hatchable.com/mcp

Useful flags: -s, --scope user|project (default project), -H, --header "Name: value" for a static auth header, --timeout <ms>, --trust to skip per-call confirmations for that server, and --include-tools or --exclude-tools to allowlist or hide tools. gemini mcp list prints what is configured, gemini mcp remove <name> deletes an entry, and gemini mcp disable <name> keeps it on file but switched off.

2. Edit settings.json by hand

A remote server that speaks Streamable HTTP goes under httpUrl. The older SSE transport uses url, and a local process uses command plus args. The same Hatchable entry as JSON:

{
  "mcpServers": {
    "hatchable": {
      "httpUrl": "https://hatchable.com/mcp"
    }
  }
}

Other keys you will meet in Google's reference: headers (an object of HTTP headers), env, timeout in milliseconds, trust, includeTools, excludeTools, and an oauth object for servers that need a pre-registered client. The full schema is on the official MCP servers page.

OAuth or a header: how the server authenticates you

Two patterns cover nearly every remote server. Servers that speak OAuth (Hatchable does) need nothing in the config: Gemini CLI tries to connect, gets a 401, discovers the authorization endpoints, opens your browser, and stores the tokens it gets back. If the browser does not open on its own, run /mcp auth hatchable inside a session. Servers that expect a static token take it as a header instead: -H "Authorization: Bearer YOUR_TOKEN" on the command line, or a headers object in the JSON. Prefer OAuth where it is offered. Nothing secret sits in a file, and tokens refresh without you.

Project scope or user scope

The command defaults to project scope, which writes .gemini/settings.json in the current directory, so the server is available only when you start Gemini CLI there. Pass -s user (or edit ~/.gemini/settings.json) for a server you want everywhere. A project-scoped file can be committed so a team shares the same tools, which is one more reason to keep credentials out of it and let OAuth sign each person in.

Check that it loaded

Start gemini somewhere the config applies and type /mcp. The default view (/mcp list) prints each server with its status and tools. /mcp desc adds tool descriptions, /mcp schema adds the full schemas, /mcp auth lists servers waiting on OAuth, and /mcp reload reconnects everything and rediscovers tools. Outside a session, gemini mcp list reads the same config. The first time the model calls a tool you get a confirmation prompt, with options to always allow that tool or the whole server; --trust at add time turns those prompts off for a server you fully trust.

Worked example: Gemini CLI building and deploying on Hatchable

Hatchable is the platform where AI-built apps go live, reached through one MCP server. Connected to it, Gemini CLI can create a project, write the files, deploy, and hand back a real URL, with a private Postgres database, sign-in for the app's users, email, scheduled jobs and file storage already attached to the project. Start to finish:

1. Add the server

   gemini mcp add -s user --transport http hatchable https://hatchable.com/mcp. User scope, so every session can use it.

2. Sign in

   Run gemini, then /mcp auth hatchable. A browser tab opens on hatchable.com. Approve, and the free account is created in the same step. No API key to paste.

3. Confirm the tools

   /mcp should now list hatchable as connected, with tools for creating projects, writing files, running SQL and deploying.

4. Ask it to build and deploy something

   Something like: "Build a simple bookmarks app with a Postgres table and an add form, deploy it on Hatchable, and give me the URL." Gemini CLI calls the tools in order, asks you to approve each new one, and finishes with a live your-app.hatchable.site link. Ask for changes in the same session and it redeploys.

New projects are private until you publish one. The free plan covers unlimited private projects and one published app with no card; Builder is $12 a month for unlimited published apps. What each tool does is listed in the MCP developer docs, and the platform side (database, auth, email, cron) is on features/mcp.

Gemini CLI or the Gemini app's Spark route

The same Hatchable server also connects to the Gemini app, by a different door: Spark's Connected Apps, where you paste the URL as a custom app and click through a few security screens. That route suits people who work in the Gemini app rather than a terminal, and the setup is clicks instead of a config file; it is written up screen by screen in connect Hatchable to Gemini. Gemini CLI is the better fit when the work already lives in a repo or a shell, or when you want a server scoped to one project.

Troubleshooting

• Failed to connect. Most often the transport: the command defaulted to stdio, or the JSON used url for a Streamable HTTP server. Re-add with --transport http or switch the key to httpUrl.
• Needs authentication. Run /mcp auth <name> and finish the sign-in in the browser tab it opens.
• Server missing from /mcp. Check which scope you added it to. A project-scoped entry only loads when Gemini CLI starts in that directory.
• Tools look stale. /mcp reload rediscovers them without restarting.

Details above reflect Google's Gemini CLI documentation as of August 2026. Flags and defaults can change between releases, so gemini mcp add --help is the final word for the version you have installed.