---
name: plungeai-in-claude-code
description: "Connect the Claude Code CLI to PlungeAI (Ocean Studio) over MCP — 'claude mcp add' one-liner, project-scoped .mcp.json with an env-var key, the skills/plugin install path, and a plungeai_whoami + plungeai_list_agents verify. Use when the user is in Claude Code and says connect / install / set up PlungeAI, add an MCP server, mentions claude mcp add or ozk_, or a PlungeAI tool call in Claude Code is failing. For claude.ai web or Claude Desktop use plungeai-in-claude-ai; 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 Claude Code

Claude Code 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.
- Claude Code CLI installed and on PATH (`claude --version`).

## Connect (once)

### Terminal one-liner (simplest)

    claude mcp add --transport http plungeai https://mcp.plungeai.com/v1 \
      --header "Authorization: Bearer ozk_YOUR_KEY" --scope user

- Default scope is `local` — this project only, stored in `~/.claude.json`.
  `--scope user` makes the server available in every project (same file).
- **Never `--scope project` with a literal key** — that writes the key into
  `.mcp.json` inside the repo, which gets committed.

### Project-scoped `.mcp.json` (committed-safe, env-var key)

Use this when the team should share the server definition in the repo
without anyone's literal key landing in git:

    {
      "mcpServers": {
        "plungeai": {
          "type": "http",
          "url": "https://mcp.plungeai.com/v1",
          "headers": { "Authorization": "Bearer ${PLUNGEAI_API_KEY}" }
        }
      }
    }

Export `PLUNGEAI_API_KEY` in each developer's own shell before launching
Claude Code — the file itself never holds a literal key, so it's safe to
commit.

## Verify

1. `claude mcp list` (or `/mcp` inside a session) shows `plungeai` connected.
2. Ask Claude: "use plungeai_whoami to confirm my identity" → an identity
   card (user id, auth tier, key label, rate window, server).
3. "use plungeai_list_agents to search 'web search'" → live results from the
   active agent catalog — proves the catalog is reachable, not just auth.

## Quirks

- `tools/list` is authoritative: a key can be fenced to a subset of
  `plungeai_*` tools — seeing fewer tools than a colleague is policy, not a
  bug.
- Money-verb operations (payments, sends) still stop: a gated call pauses
  with a structured `needs_approval` outcome (relay it, then
  `plungeai_continue` once the user decides) regardless of any auto-approve
  setting — never retry blind, never approve on your own.
- Long CNL workflow runs: prefer `mode: "async"` +
  `plungeai_get_workflow_status` polling over one long synchronous call.
- Skills for the agent — teach PlungeAI conventions (discovery-first, CNL
  authoring) as an installable skill directory:
  - **Public repo `PlungeAI/plungeai-agent-skills` — once published**:
    `npx skills add PlungeAI/plungeai-agent-skills` (installs into
    `.agents/skills/` or `.claude/skills/`, `-g` for the user-level home
    `~/.claude/skills/`), or `claude plugin marketplace add
    PlungeAI/plungeai-agent-skills` then `claude plugin install
    plungeai@plungeai`.
  - **Working today:** download https://mcp.plungeai.com/skill.zip and
    unzip into `.claude/skills/` (or `~/.claude/skills/`).
- 401 (`Invalid API key`, or `No valid authentication provided...` if the
  header itself is missing) → key typo'd, pasted with whitespace, or the
  header never made it into `~/.claude.json` / `.mcp.json` — re-check the
  header field, not the key value.
- Connected but no `plungeai_*` tools listed → restart the session after any
  config edit before debugging further.

## 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**.
- CNL workflow YAML authoring: **plungeai-workflows**.
- An unlisted but MCP-capable client, or the shared connect concepts (native
  remote vs. stdio bridge, key hygiene): **plungeai-mcp-setup**.