Gemini CLI

Gemini CLI connects to Zephex over Streamable HTTP with OAuth discovery. The config contains only the MCP URL and transport type, not a Bearer header or pasted API key.

OVERVIEW

Gemini CLI is Google's open-source terminal AI agent backed by Gemini 2.5 Pro. It supports MCP servers via Streamable HTTP and handles OAuth through Dynamic Client Registration auto-discovery. After adding the config, run `/mcp auth zephex` inside a Gemini session to trigger the browser OAuth flow.

CONFIG FILE LOCATION

~/.gemini/settings.json. Global config. Applies to all Gemini CLI sessions.

PREREQUISITES

Gemini CLI installed with `npm install -g @google/gemini-cli` or `npx @google/gemini-cli`.
A Zephex account at zephex.dev/signup.
A Google account for the Gemini CLI free tier or `GOOGLE_API_KEY` for API-key mode.
No Zephex API key needed. Authentication is handled through the OAuth browser flow.

CONFIG

Paste the JSON exactly as shown under `mcpServers`. Use `url` with `type: http`. The Zephex config contains only the URL and transport because authentication happens through OAuth discovery instead of a pasted key.

Do not add an Authorization header or paste a Zephex API key into this file. Gemini CLI should authenticate from the hosted MCP URL through the browser flow.

~/.gemini/settings.json

{  "mcpServers": {    "zephex": {      "url": "https://zephex.dev/mcp",      "type": "http"    }  }}

AUTH

Save ~/.gemini/settings.json.
Start Gemini CLI by running `gemini` in your terminal.
Inside the session, run `/mcp auth zephex`.
A browser window opens. Log in to your Zephex account.
After login, return to the terminal. Gemini CLI confirms the connection.
For servers that support OAuth discovery, Gemini CLI can also auto-discover and auth without the manual `/mcp auth` step.

VERIFY

Confirm the remote MCP server is loaded before you rely on it in normal prompts.

Run `/mcp` inside a Gemini session.
You should see "zephex" listed with status "connected".
Ask Gemini: "what tools are available from zephex?" You should see all 10 tools.

COMMON ISSUES

`/mcp auth zephex` returns "server not found"

Make sure the settings file was saved before starting the session, then restart Gemini CLI after editing the config.

`"httpUrl" field deprecated` warning

Use `url` instead of `httpUrl`. The config on this page already uses the current field names.

Connection works but tools are missing

Run `/mcp` and check whether the server is authenticated. If it is connected but not authenticated, run `/mcp auth zephex` again.

DCR registration fails

Update Gemini CLI to the latest version with `npm update -g @google/gemini-cli` and try again.

If the editor still does not connect, return to Quickstart or check Connection Issues.