---
name: plungeai-in-gemini-cli
description: "Connect Gemini CLI to PlungeAI (Ocean Studio) over MCP — a ~/.gemini/settings.json entry using httpUrl (not url, which is SSE-only and 405s), the mcp-remote bridge fallback, /mcp reload after edits, and a plungeai_whoami + plungeai_list_agents verify. Use when the user is in Gemini CLI and says connect / install / set up PlungeAI, mentions settings.json or httpUrl, or plungeai_* tools come up empty. For another editor use its plungeai-in-<tool> skill; for an unlisted but MCP-capable client use plungeai-mcp-setup's generic client config."
---

# PlungeAI in Gemini CLI

Gemini CLI talks to PlungeAI over the Streamable HTTP MCP server at
`https://mcp.plungeai.com/v1`. One `ozk_` bearer key authenticates it (and
the One API, if generated code calls PlungeAI directly).

## Prerequisites

- An `ozk_` key: Dashboard → **One API → Keys** (https://dashboard.plungeai.com) —
  self-service, shown once, copy it now.

## Connect (once)

Merge into `~/.gemini/settings.json` (user-level — the right home for the
key):

    {
      "mcpServers": {
        "plungeai": {
          "httpUrl": "https://mcp.plungeai.com/v1",
          "headers": { "Authorization": "Bearer ozk_YOUR_KEY" }
        }
      }
    }

**The key name is `httpUrl`** — Gemini CLI reserves `url` for SSE servers,
and the PlungeAI endpoint rejects SSE-style GETs with an immediate 405, so a
`url` entry fails to connect. This is the #1 misconfiguration on this tool.

If the build lacks `httpUrl`, bridge with mcp-remote instead:

    {
      "mcpServers": {
        "plungeai": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.plungeai.com/v1",
                   "--header", "Authorization: Bearer ozk_YOUR_KEY"]
        }
      }
    }

A project-scoped `.gemini/settings.json` gets committed — keep the literal
key in the user-level file only.

## Verify

1. `/mcp` inside the CLI lists `plungeai` with its tools.
2. Ask Gemini: "use plungeai_whoami to confirm my identity" → an identity
   card.
3. Transport-independent check:
   `curl -H "Authorization: Bearer ozk_YOUR_KEY" https://api.plungeai.com/v1/agents`
   → HTTP 200 JSON. Then "use plungeai_list_agents to search 'web search'"
   from inside the CLI → live results from the active agent catalog.

## Quirks

- `/mcp reload` re-connects all MCP servers and re-discovers tools after a
  settings edit — `/mcp refresh` exists on some builds but has had reload
  bugs upstream; if either doesn't pick up the change, restart the CLI.
- Per-tool confirmation is the default; `"trust": true` on the server entry
  skips it. Money-verb PlungeAI operations still pause with a structured
  `needs_approval` outcome regardless — relay it, then `plungeai_continue`.
- A previously working setup whose tool list comes up empty usually means
  the key was revoked/expired (the handshake now 401s) — re-check with the
  curl line above before touching the config.
- A `GEMINI.md` line with a discovery-first reminder ("PlungeAI agent ids
  come from a live `plungeai_list_agents` search — never from memory")
  keeps every session honest. Context files are committed — never put the
  key there.

## Where next

- Operating the `plungeai_*` tools once connected: **plungeai-mcp-setup**.
- Writing code that calls `https://api.plungeai.com` directly: **plungeai-api-setup**.
- Picking MCP vs the One API for a given job: **choose-your-plungeai-door**.
- An unlisted but MCP-capable client, or the shared connect concepts (native
  remote vs. stdio bridge, key hygiene): **plungeai-mcp-setup**.