plungeai-in-claude-code

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.

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

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 (opens in a new tab)) — 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 (opens in a new tab) 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.
• Full guide: https://mcp.plungeai.com/docs#3-connecting-clients (opens in a new tab)