Gemini CLI

Tier 2: configuration verified on 2026-10-21 against the Gemini CLI MCP reference. Gemini CLI was not installed on the verification machine. The command, the settings.json shape, the OAuth behavior and the callback rules below are quoted from the current documentation; the broker endpoints were checked live.

Before you start

• Gemini CLI installed and signed in to a Google account.
• A browser on the same machine, signed in to the GitHub account that owns the agents. The OAuth flow needs a local browser; it does not work in a headless container or a plain SSH session.
• A verified human account with the master delegation agreement signed. See the agent quickstart.
• The server URL has no trailing slash: https://agentregistrar.dev/mcp.

Add the server

gemini mcp add --transport http agentregistrar https://agentregistrar.dev/mcp

The default scope is project, which writes .gemini/settings.json; add --scope user to write ~/.gemini/settings.json. The command adds this entry:

{
  "mcpServers": {
    "agentregistrar": {
      "httpUrl": "https://agentregistrar.dev/mcp"
    }
  }
}

The property names matter. httpUrl selects the Streamable HTTP transport. url is the older SSE transport and would connect to the wrong protocol for this endpoint. timeout is optional and is in milliseconds; leave it out unless you have a reason to set it, because the client default is ten minutes. If you set it, use a value above 60000: inbox_wait_for_email can wait up to 60 seconds, and a shorter client timeout aborts a legitimate wait. Do not add an Authorization header: OAuth supplies the credential, and a configured header bypasses the client's discovery flow.

Authorize

gemini mcp list

The server is listed with its connection state. Inside the CLI, run:

/mcp

The command lists every configured server with its state and tools. To sign in, run:

/mcp auth

Choose agentregistrar. Gemini CLI detects the 401, discovers the broker's authorization server, opens a browser and stores the token in ~/.gemini/mcp-oauth-tokens.json. Dynamic client registration is used when the server supports it; this broker does.

The callback is http://localhost:<port>/oauth/callback on a port the client chooses. The broker accepts loopback callbacks on any port for a registered loopback URI. If you need a fixed port, set redirectUri in the server's oauth block and register the same URI.

The broker's authorization server metadata does not advertise the RFC 9207 issuer parameter, so Gemini CLI accepts a callback without iss, which is the documented behavior for such a server.

Verify the connection

/mcp

The server should show CONNECTED with the nine broker tools: identity_register, identity_whoami, identity_signup, identity_prove, identity_record_signup, inbox_list, inbox_read, inbox_wait_for_email and inbox_send. Gemini CLI prefixes discovered tools with the server name, so they appear with an mcp_agentregistrar_ prefix.

A server that connects with no tools is closed by the client after discovery; if the server disappears from the list, read the connection error in /mcp and the debug output from gemini --debug.

First call

Use the agentregistrar MCP server. Call identity_register with {"name": "gemini-agent", "harness": "gemini-cli"}, then call identity_whoami with no arguments and show the result.

identity_register creates the agent and binds it to this OAuth session; identity_whoami then returns the same agent. Register first, because a bare identity_whoami auto-provisions the broker defaults, opencode-agent with harness: "opencode-v2", for every client. Registration is idempotent: the agent bound to the token is returned whatever name you pass later, so a different name needs a new OAuth session.

The shape below is illustrative, with synthetic ids and address. It is the identity_whoami result; identity_register returns the same core profile plus created_at. The nested agent mirror, signup_state and docs are omitted for length.

{
  "id": "agt_01JAB2C3D4E5F6G7H8J9K0G1H2",
  "name": "gemini-agent",
  "slug": "gemini-agent-k0g1h2",
  "harness": "gemini-cli",
  "email_address": "gemini-agent-k0g1h2@agents.agentregistrar.dev",
  "status": "active",
  "scopes": ["tos:accept", "signup:free_tier", "inbox:read", "inbox:send"],
  "human_owner": { "...": "..." }
}

Continue

The full signup is in the agent quickstart. Tool inputs and error codes are in the reference.

Troubleshooting

The client redacts sensitive environment variables before starting MCP processes. That does not affect this server, which needs no environment variables.

Remove and reset

gemini mcp remove agentregistrar

Use gemini mcp disable agentregistrar to keep the entry without connecting, and gemini mcp enable agentregistrar to restore it. Removing the server does not necessarily delete the stored token; delete ~/.gemini/mcp-oauth-tokens.json if you need a clean sign-in as another account.

Verification record

Tier 1 needs a recorded transcript from an installed client. That transcript does not exist yet, and the product transition above means this page should be re-checked before anyone claims it.