---
name: plungeai-in-windsurf
description: "Connect Windsurf (Cascade) to PlungeAI (Ocean Studio) over MCP — a ~/.codeium/windsurf/mcp_config.json entry using serverUrl, the mcp-remote bridge fallback for stdio-only builds, the 100-tool cap, and a plungeai_whoami + plungeai_list_agents verify. Use when the user is in Windsurf/Cascade and says connect / install / set up PlungeAI, mentions mcp_config.json or serverUrl, or plungeai_* tools aren't showing up. 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 Windsurf (Cascade)

Windsurf 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). No install-page
deeplink exists for Windsurf — it is a config-file tool.

## Prerequisites

- An `ozk_` key: Dashboard → **One API → Keys** (https://dashboard.plungeai.com) —
  self-service, shown once, copy it now.

## Connect (once)

Merge into `~/.codeium/windsurf/mcp_config.json` (user-level — the right
home for the key), then reload the MCP servers from Cascade's MCP panel or
restart Windsurf:

    {
      "mcpServers": {
        "plungeai": {
          "serverUrl": "https://mcp.plungeai.com/v1",
          "headers": { "Authorization": "Bearer ozk_YOUR_KEY" }
        }
      }
    }

`serverUrl` is the documented key for remote servers (the vendor docs also
accept `url`; every vendor example uses `serverUrl` — stick with it).

Older, stdio-only builds bridge with mcp-remote instead:

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

## Verify

1. Cascade's MCP panel shows `plungeai` with tools after a refresh.
2. In Cascade: "use plungeai_whoami to confirm my identity" → an identity
   card.
3. "use plungeai_list_agents to search 'web search'" → live results from the
   active agent catalog.

## Quirks

- Config edits are not hot-reloaded — refresh/reload the MCP panel (or
  restart Windsurf) after every change, before debugging anything else.
- Tool cap: Cascade has a limit of roughly 100 total tools across all
  servers. If `plungeai_*` tools are missing, disable unused servers and
  refresh.
- Discovery-first rules live in project `.windsurf/rules/*.md` (the legacy
  single-file `.windsurfrules` is also still read) or the global
  `~/.codeium/windsurf/memories/global_rules.md`. Rules files are
  committed — never put the key there.
- Money-verb PlungeAI operations still pause with a structured
  `needs_approval` outcome (relay it, then `plungeai_continue`) regardless
  of any auto-run setting.

## 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**.