> ## 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-claude-ai

> Connect claude.ai web or Claude Desktop to PlungeAI (Ocean Studio) — Desktop live tools via the mcp-remote bridge in claude_desktop_config.json (OAuth isn't available yet, hence the bridge), claude.ai web via skill.zip upload, and a plungeai_whoami + plungeai_list_agents verify for Desktop.


Connect claude.ai web or Claude Desktop to PlungeAI (Ocean Studio) — Desktop live tools via the mcp-remote bridge in claude_desktop_config.json (OAuth isn't available yet, hence the bridge), claude.ai web via skill.zip upload, and a plungeai_whoami + plungeai_list_agents verify for Desktop. Use when the user is on claude.ai or Claude Desktop and says connect / install / set up PlungeAI, mentions claude_desktop_config.json, Customize → Skills, or a PlungeAI tool call there is failing. For the Claude Code CLI use plungeai-in-claude-code; for an unlisted but MCP-capable client use plungeai-mcp-setup's generic client config.

[Download zip](https://skills.plungeai.com/plungeai-in-claude-ai.zip) · [View raw SKILL.md](https://skills.plungeai.com/plungeai-in-claude-ai/SKILL.md)

Two different surfaces, two different capabilities:

| Surface | What it gets |
|---|---|
| **Claude Desktop** | live `plungeai_*` MCP tools, via a bridge (below) |
| **claude.ai (web)** | a PlungeAI *skill* upload — Claude produces paste-ready CNL workflows for Ocean Studio, not live tool calls (claude.ai has no custom-connector bearer-header field yet) |

## Prerequisites

- An `ozk_` key: Dashboard → **One API → Keys** (https://dashboard.plungeai.com) —
  self-service, shown once, copy it now.
- Desktop only: Node.js installed (the bridge runs via `npx`).

## Connect (once) — Claude Desktop

**Why a bridge:** Settings → Connectors → Add custom connector authenticates
through OAuth only (no bearer-header field), and PlungeAI OAuth hasn't
shipped. Until it does, Desktop connects through the `mcp-remote` stdio
bridge.

Settings → Developer → **Edit Config** opens the file — macOS
`~/Library/Application Support/Claude/claude_desktop_config.json`, Windows
`%APPDATA%\Claude\claude_desktop_config.json`. Merge:

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

Quit Claude Desktop completely and relaunch — the config is only read at
start.

## Connect (once) — claude.ai web (skill only)

Needs code execution enabled first: **Settings → Capabilities** → turn on
**Code execution and file creation** (a prerequisite for any custom skill
upload, not PlungeAI-specific). Then **Customize → Skills → + → Upload a
skill** — upload https://mcp.plungeai.com/skill.zip. This teaches Claude
PlungeAI conventions; it does not give claude.ai a live MCP connection.

## Verify (Claude Desktop)

1. Ask Claude: "use plungeai_whoami to confirm my identity" → an identity
   card (user id, auth tier, key label, rate window, server).
2. "use plungeai_list_agents to search 'web search'" → live results from the
   active agent catalog.

claude.ai web has no live tool call to verify — a successfully uploaded skill
is the only signal; ask Claude to draft a PlungeAI CNL workflow to confirm it
loaded.

## The tool map (Claude Desktop)

Desktop gets the live tools; claude.ai web (skill upload) has none. This is
what the 22 tools take, so Claude can plan a call before making it:

```text
PlungeAI MCP 2.7.0. Server https://mcp.plungeai.com/v1 (Streamable HTTP), Authorization: Bearer ozk_YOUR_KEY. 22 tools; tools/list is authoritative (a fenced key sees fewer).
Pass user_request (the user's own words, verbatim) on every call. Output is final markdown: relay it verbatim. format:"json" returns machine-readable output.
FIND: plungeai_list_agents {search, category, agent_id, kind: agents|personas|experts|skills|models|workflows|connectors} = the live registry; ids come only from here.
  plungeai_get_tool_contract {agent_id} = schema, operations, credential status. plungeai_whoami = identity, tier, key label, rate window.
RUN: plungeai_execute_agent {agent, prompt} (always sync). plungeai_execute_tool {agent_id, operation, params, mode}. plungeai_run_mission {goal, allowed_tools, max_iterations} (async by default).
  plungeai_execute_workflow {workflow_id | workflow_yaml, input, inputs, mode: sync|async}.
RUNS: plungeai_get_workflow_status {execution_id} polls (and carries continuation). plungeai_get_result {execution_id, task_id?}. plungeai_followup {execution_id, prompt}.
  plungeai_continue {execution_id, approve | message}. plungeai_executions {action: list|get|output|conversation|delete|cancel|steer|files; message for steer}.
WORKFLOWS: plungeai_list_workflows {kind: workflow|agent|bot|campaign, folder, search}. plungeai_build_workflow {goal | workflow_id + instruction}. plungeai_templates {action: list|get|use}.
  plungeai_workflow {action: create|get|update|delete|list_versions|get_version|save_version|restore_version|a2a_door|permissions_get|permissions_set|files|file|inbox|bindings|bind|unbind|groups|group_set|group_delete|group_thread; kind}.
SCHEDULES: plungeai_schedule {action: stats|list|get|create|update|pause|resume|delete|run_now|runs|wake|webhook_mint|webhook_list|webhook_delete|email_mint|email_list|email_delete|hooks_mint|hooks_list|hooks_delete};
  create takes job_type agent|query|workflow|heartbeat, target, schedule (cron, or "@once" with run_at = ISO-8601 with a UTC offset).
MEMORY: plungeai_memory {action: recall|remember|search_runs|get_run}. plungeai_learn {action: learn|list|forget} (learn defaults to async). plungeai_chat {action: send|list_sessions|history|new}.
OUTCOMES: status ok | needs_input | needs_connection | needs_api_key | needs_approval | unavailable | error, with remediation.actions. A paused run ends with a pause block: relay it verbatim,
  call plungeai_continue only after the user decides (approve:true for an explicit yes, message for anything else). Never approve for the user; never retry the identical call blind.
```

## Quirks

- **Windows:** Desktop does not escape spaces inside `args` — if the bridge
  401s only on Windows, replace the header arg with
  `"--header", "Authorization:${AUTH_HEADER}"` plus
  `"env": { "AUTH_HEADER": "Bearer ozk_YOUR_KEY" }` in the same entry.
- Logs: `~/Library/Logs/Claude/mcp*.log` (macOS) ·
  `%APPDATA%\Claude\logs` (Windows) — check these before re-editing the
  config.
- The bridge is an `npx` process — a cold start can take a few seconds; if
  tools "never appear," wait, then check the logs above.
- Long CNL workflow runs: prefer `mode: "async"` +
  `plungeai_get_workflow_status` polling — Desktop caps a single synchronous
  tool call.
- Money-verb operations (payments, sends) still stop: a gated call pauses
  with a structured `needs_approval` outcome — relay it to the user, then
  `plungeai_continue`; never retry blind.
- 401 through the bridge but the key looks right → whitespace or a missing
  `ozk_` prefix; re-paste it into the config.

## Where next

- The Claude Code CLI instead of Desktop/web: **plungeai-in-claude-code**.
- 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