> ## Documentation Index > Fetch the complete documentation index at: https://www.plungeai.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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. 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- skill; for an unlisted but MCP-capable client use plungeai-mcp-setup's generic client config. [Download zip](https://skills.plungeai.com/plungeai-in-gemini-cli.zip) · [View raw SKILL.md](https://skills.plungeai.com/plungeai-in-gemini-cli/SKILL.md) 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. ## What the agent should know (One API 2.3.0) The `plungeai_*` tools operate PlungeAI from chat; the block below is for the code the agent writes against `https://api.plungeai.com`. This skill already carries it. To make it always-on for a project, paste it into `GEMINI.md` — that file is committed, so never put the key in it. The minimal saved-workflow body (`workflow:` / `tasks:` YAML) is in **plungeai-api-setup**. ```text PlungeAI One API 2.3.0. Base URL https://api.plungeai.com. Spec: GET /v1/openapi.json (no auth) - never invent a route. AUTH: Authorization: Bearer ozk_YOUR_KEY on every call; key in an env var, server side only. When a connector attaches auth, NEVER add your own Authorization header. ME: GET /v1/whoami -> {user_id, via, tier, key_label}. GET /v1/key -> {data:{label, limit, usage, rate_limit}}. FIND (never from memory): GET /v1/discovery/search?q=&kind=agents -> {cards} (without kind, skill cards come first). POST /v1/discovery/resolve {task}. GET /v1/agents. GET /v1/tools. GET /v1/tools/{id} = the contract. DOOR 1, one agent or tool: POST /v1/agents/{id}/execute {prompt|input, sync?, model?} -> 200 {content, workflow_id, task_id, request_id}. POST /v1/tools/{id}/execute {operation, params} -> {ok, content, outcome}; 422 invalid_params echoes the contract. DOOR 2, saved workflow or bot: POST /v1/workflows/{id}/execute {input?, inputs?} -> {success, workflow_id, final_task_id, request_id, content}, synchronous. POST /v1/workflows/{id}/execute-stream = SSE. Inline YAML: POST /v1/workflows/execute. No content? GET /v1/workflows/results/{workflowId}/{taskId} (taskId = final_task_id). DOOR 3, Agent Call: POST /v1/execute, the body is the program: {agent:"[@n]", input} or {workflow:{...}} or {tasks:[...]}. dry_run:true plans without running; on_behalf_of:"" uses that customer's connections. ASYNC: POST /v1/agents/{id}/execute {sync:false} -> 202 {workflow_id, task_id, request_id}; redeem GET /v1/agents/results/{workflowId}/{taskId} -> {content}; 404 not_ready = poll, 2s+. EXECUTIONS: the run id is the body's workflow_id (also the x-execution-id header, and your x-trace-id UUID if you sent one; replaying one is 409 duplicate_execution_id). GET /v1/executions (source, status, workflow_id). GET /v1/executions/{id}: running | completed | incomplete | failed | cancelled | needs_input | needs_approval. GET /v1/executions/{id}/output -> {content, steps}. GET /v1/executions/{id}/files. GET /v1/executions/{id}/conversation. DELETE /v1/executions/{id}. GET /v1/executions/{id}/stream = SSE. POST /v1/executions/{id}/continue {answer | approve, allow_scope: once|run|always}. POST /v1/executions/{id}/followup {text}. POST /v1/executions/{id}/cancel. POST /v1/executions/{id}/steer {text} queues a message for a live run (202), else 409 execution_finished. WORKFLOWS: GET|POST /v1/workflows. GET|PATCH|DELETE /v1/workflows/{id}. GET|POST /v1/workflows/{id}/versions. POST /v1/workflows/{id}/versions/{versionId}/restore. Save needs {name, kind, yaml}; kind = workflow|agent|bot|campaign. GET /v1/workflows lists every kind unless ?kind=bot (or campaign). 422 invalid_workflow lists errors, writes nothing. SCHEDULES: POST /v1/schedules {name, schedule, workflow_id, timezone?, parameters?}; schedule = a cron, or "@once" with run_at (ISO-8601 WITH a UTC offset, in the future); 400 run_at_required | run_at_past. GET /v1/schedules. GET|PATCH|DELETE /v1/schedules/{id}. GET /v1/schedules/{id}/runs (execution_id per run). POST /v1/schedules/{id}/run. POST /v1/schedules/{id}/pause. POST /v1/schedules/{id}/resume. POST /v1/schedules/{id}/wake {note?, in?} fires it once, now or later. TRIGGERS (every call names schedule_id; a secret is shown once): GET|POST /v1/triggers/webhook. DELETE /v1/triggers/webhook/{token}. POST /v1/triggers/webhook/{token}/rotate. The same four under /v1/triggers/email {allowed_from}. GET|POST /v1/triggers/hooks {url, events}. DELETE /v1/triggers/hooks/{id}. PERMISSIONS: GET|PUT /v1/workflows/{id}/permissions {classes:{send|write|pay|delete: allow|ask|deny|hand_off}, locks, budget_usd_run, budget_usd_month}; locks need a team admin (403 lock_admin_required). BOT DATA: GET /v1/workflows/{id}/workspace-files. GET /v1/workflows/{id}/workspace-files/download?path=. GET /v1/workflows/{id}/inbox. GET|POST /v1/workflows/{id}/bindings {channel, sender_id}. DELETE /v1/workflows/{id}/bindings/{channel}/{sender_id}. GET /v1/channels. POST /v1/channels/pair {channel}. GET|POST /v1/bot-groups {name, members = 2-6 of your bot ids}. PUT|DELETE /v1/bot-groups/{id}. GET /v1/bot-groups/{id}/thread. MEMORY: GET /v1/memory/recall?q=. POST /v1/memory/remember {text, scope: memory|user}. POST /v1/memory/forget {id | text}. GET /v1/memory/runs?q= (q required). GET /v1/memory/runs/{id}. SKILLS: GET /v1/skills. POST /v1/skills/learn {name, body} saves the body you send (it does not distill a URL). DELETE /v1/skills/{id}. TEMPLATES: GET /v1/templates?kind=workflow|agent|bot. GET /v1/templates/{id}. POST /v1/templates/{id}/use {name?} -> 201 {workflow}. CONNECTIONS: GET /v1/connections. POST /v1/connections/{provider} {api_key, on_behalf_of?}. DELETE /v1/connections/{provider}. POST /v1/connections/{provider}/link -> {url, expires_at}. MODELS (OpenAI-shaped, Bearer only): GET /v1/models. POST /v1/chat/completions. POST /v1/embeddings. TRACES: GET /v1/traces/{id}, id = the run's workflow_id. LISTS: {workflows|executions|schedules|cards:[...], total, limit, offset, has_more}; POST /v1/schedules -> {schedule}. ERRORS: {"error":{"code","message"}} plus an X-Error-Code header. 400 validation; 401 unauthorized; 403 refused | agent_not_active; 404 _not_found (a stranger's id too); 409 approval_required, or not_paused | execution_finished | duplicate_execution_id | name_taken; 422 invalid_params; 429 rate_limited + Retry-After; 502/503 retry once. 424 connection_required | credential_required carries error.connect {provider, method, link}: connect via POST /v1/connections/{provider} or its /link. FENCES: 403 refused is final - surface it, never retry. 409 approval_required is a human boundary - never approve for the user. tools/{id}/execute: a human approves in Studio, then re-issue. A paused agent reply: re-send with approved:true plus its action_token (both). A run reading needs_approval: POST /v1/executions/{id}/continue, never the original call. ``` ## 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