Connect an MCP Server to Gemini CLI (gemini mcp add)

To connect an MCP server to Gemini CLI, run gemini mcp add with a name and a URL, or add the server by hand under mcpServers in settings.json. Remote servers use the httpUrl field. Local ones use command. Below are the exact command, the config, and two ways to send an API key.

Add a remote server with one command

Say you have a hosted MCP server and an API key. This adds it with a bearer header:

gemini mcp add --transport http mcpifex https://mcpifex.com/mcp \
  --header "Authorization: Bearer <YOUR_MCPX_KEY>"

If you'd rather skip the header, the same key works as the first path segment of the URL:

gemini mcp add --transport http mcpifex https://mcpifex.com/mcp/<YOUR_MCPX_KEY>

Treat either form like a password. Anyone who holds it can call the tools enabled for that key. Add -s user to make the entry available outside the current project.

All the gemini mcp add options

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

  -s, --scope        user | project   (default: project)
  -t, --transport     stdio | sse | http   (default: stdio)
  -e, --env           KEY=value
  -H, --header        "Name: value"
  --timeout           milliseconds
  --trust
  --include-tools
  --exclude-tools

gemini mcp list shows every configured server and gemini mcp remove <name> deletes one. gemini mcp enable and gemini mcp disable <name> toggle a server without touching settings.json.

Edit settings.json directly

User scope lives in ~/.gemini/settings.json and project scope in .gemini/settings.json. Merge this under mcpServers:

{
  "mcpServers": {
    "mcpifex": {
      "httpUrl": "https://mcpifex.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_MCPX_KEY>"
      }
    }
  }
}

Which field you set picks the transport:

• command, with optional args, cwd and env, spawns a local process over stdio.
• url is the legacy SSE transport.
• httpUrl is Streamable HTTP, the current transport for remote servers. There is no local process.

A remote entry also accepts headers, timeout (milliseconds, default 600000), trust (default false) and includeTools / excludeTools. Setting trust to true skips Gemini CLI's per-call confirmation prompt for that server.

For a command entry, env values expand $VAR_NAME or ${VAR_NAME} on POSIX and %VAR_NAME% on Windows.

Gemini CLI also strips host variables that look like *TOKEN*, *SECRET*, *PASSWORD*, *KEY*, *AUTH* or *CREDENTIAL* from what a stdio server receives, unless you list them in that server's own env block.

Verify the connection

Start an interactive Gemini CLI session and run /mcp. It shows each server's connection status and the tools it found. From a terminal, gemini mcp list gives the status without opening a session. /mcp enable mcpifex and /mcp disable mcpifex toggle the server for the rest of the session.

Limit which tools Gemini can use

Gemini CLI lets you filter tools per server with includeTools and excludeTools in the entry, or --include-tools and --exclude-tools on gemini mcp add. If a tool appears in both, excludeTools wins. This filter lives in Gemini CLI only, so another client using the same server doesn't inherit it. For a server-side limit, see MCP security.

OAuth or a static header?

As of September 2026, Gemini CLI can also run an OAuth flow for an SSE or HTTP server. It discovers the OAuth endpoints on a 401 response, or you supply an oauth block by hand, and /mcp auth [serverName] starts the login.

That flow opens a browser and listens on localhost for the callback. It doesn't work over a headless SSH session or in CI. A static bearer header has no browser step, so it behaves the same everywhere.

Troubleshooting

• The server shows disconnected in /mcp. Check the URL and that you used httpUrl (or --transport http), not command or url.
• 401 from the server. The key is missing, mistyped or revoked. MCPifex keys start with mcpx_.
• OAuth login hangs over SSH. The callback goes to localhost on a machine with no browser. Use a bearer header instead.
• A tool you expect is missing. Check includeTools and excludeTools first. Then check which tools are enabled for the server itself.
• Calls time out. Raise timeout on the entry, or pass --timeout when you add it.

Use hosted servers with one entry

Each local server you add to mcpServers is another process and another credential to manage. MCPifex keeps that to a single httpUrl entry. You create an instance of each server you want, such as PostgreSQL, Google Trends or Google Search Console, in the portal. Then you switch tools on or off there, and destructive tools start off. A tool you haven't enabled is refused by the gateway itself.

The quickstart walks through the whole path, and instances and tools explains what the enabled list changes. API keys and authentication covers the key. Registering is free. Revoking a key in the portal stops new calls within about a minute.