Gemini CLI MCP Setup: settings.json, gemini mcp add and the Antigravity CLI Switch

Gemini CLI reads MCP servers from the mcpServers object in settings.json: ~/.gemini/settings.json for your user, or .gemini/settings.json inside a project. The fastest way to add one is gemini mcp add <name> <command-or-url>, then type /mcp in a session to confirm it connected.

Before you start, check which CLI you are actually on. Google's docs say Gemini CLI was replaced by Antigravity CLI for unpaid-tier and Google One users on 18 June 2026. Antigravity CLI uses a different config file, covered at the end of this guide.

Checked against: the Gemini CLI MCP server docs and Google's Antigravity MCP docs on 2 November 2026.

Which CLI do you have?

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. Users with a paid API key or Gemini Code Assist Standard or Enterprise kept Gemini CLI, per Google's announcement summarized in our Google and MCP overview. If your terminal command is agy, skip to the Antigravity section.

Option 1: Add a server with gemini mcp add

The command syntax from the docs:

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

Key flags:

Examples from the docs:

# Local stdio server with two environment variables
gemini mcp add -e API_KEY=123 -e DEBUG=true my-stdio-server /path/to/server arg1 arg2 arg3

# Remote Streamable HTTP server with a bearer token
gemini mcp add --transport http --header "Authorization: Bearer abc123" secure-http https://api.example.com/mcp/

Add -s user if you want the server in every project. Leave --trust off unless you have reviewed every tool; it removes the confirmation step.

Option 2: Edit settings.json

Open ~/.gemini/settings.json (or .gemini/settings.json in a project) and add an mcpServers object. Each server needs exactly one of:

• command for a local stdio server
• url for an SSE endpoint
• httpUrl for a Streamable HTTP endpoint

This example, based on the docs' GitHub token example, runs a local server and reads the token from your shell rather than storing it:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@github/github-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}

A remote server looks like this:

{
  "mcpServers": {
    "remoteTools": {
      "httpUrl": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${MY_TOKEN}" }
    }
  }
}

Both blocks were checked against the Gemini CLI docs on 2 November 2026. Optional fields include args, env, cwd, headers, timeout (600,000 ms by default), trust and includeTools or excludeTools. Variables can use $VAR or ${VAR} on all platforms, or %VAR% on Windows. Undefined variables become empty strings.

The docs also warn: do not use underscores in server names. Use my-server, not my_server, because the policy parser splits tool names on the first underscore and rules "can fail silently."

Verify it loaded

• From the shell: gemini mcp list shows each server's name, config and connection status.
• In a session: type /mcp to see status, tools and resources. /mcp list gives more detailed diagnostics.

If a stdio server shows "Disconnected," the folder may be untrusted. The docs say stdio servers are only tested "if the current folder is trusted." Run gemini trust in that folder.

OAuth for remote servers

Gemini CLI supports OAuth 2.0 for remote SSE and HTTP servers. If a server returns 401, the CLI can discover its OAuth settings automatically. Run /mcp auth <serverName> to sign in or re-authenticate. Tokens are saved in ~/.gemini/mcp-oauth-tokens.json.

Sign-in opens a browser, so the docs note it will not work on a headless machine. Our MCP authentication guide explains the flow.

If you use Antigravity CLI instead

Google's Antigravity docs describe a different setup:

• Interactive: type /mcp in the prompt to open the MCP Manager, which shows server status and connection logs.
• Global file: ~/.gemini/config/mcp_config.json, shared with the Antigravity IDE.
• Workspace file: <workspace>/.agents/mcp_config.json.

Remote servers use serverUrl (the docs say url also works). Google's example:

{
  "mcpServers": {
    "my-remote-server": {
      "serverUrl": "https://api.example.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      },
      "timeoutSeconds": 600
    }
  }
}

The docs add that "the legacy HTTP+SSE transport and the httpUrl field aren't supported." So a Gemini CLI block with httpUrl must be changed to serverUrl when you move it. Restart the CLI after editing the file.

Common mistakes

• Adding to the wrong scope. gemini mcp add writes to the project file by default.
• Using url for a Streamable HTTP server in Gemini CLI. url means SSE there; use httpUrl.
• Copying Gemini CLI config into Antigravity unchanged. Switch httpUrl to serverUrl.
• Underscores in server names. They can break policy rules silently.

If a server fails in Gemini CLI, test it alone with the MCP Inspector (npx @modelcontextprotocol/inspector, Node 22.19.0 or newer) to see whether the fault is in the server or the config. More fixes are in our Gemini CLI MCP errors guide.

Next step

Compare Gemini's MCP support with other apps in ChatGPT vs Gemini for MCP and the client support matrix. The MCP config generator can draft a starting block.

Frequently asked questions