plungeai-in-gemini-cli

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.

Download zip (opens in a new tab) · View raw SKILL.md (opens in a new tab)

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 (opens in a new tab)) — 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

/mcp inside the CLI lists plungeai with its tools.
Ask Gemini: "use plungeai_whoami to confirm my identity" → an identity card.
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.
Full guide: https://mcp.plungeai.com/docs#3-connecting-clients (opens in a new tab)