---
name: plungeai-in-cursor
description: "Connect Cursor to PlungeAI (Ocean Studio) over MCP — the one-click install-page deeplink or a ~/.cursor/mcp.json entry, Agent/Plan-mode tool behavior, the ~40-tool cap, and a plungeai_whoami + plungeai_list_agents verify. Use when the user is in Cursor and says connect / install / set up PlungeAI, mentions mcp.json or the install page, asks whether PlungeAI works in Cursor, 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 Cursor

Cursor 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)

### One click

1. Open https://mcp.plungeai.com/install, **type the `ozk_` key into the box
   at the top**, then click **Add to Cursor**. Cursor prompts to install the
   server — confirm.
2. Cursor never asks for a header: clicked without the key, the server
   installs auth-less (401, red status) and the `headers` block must be
   added by hand afterwards (below).

### By hand

Merge into `~/.cursor/mcp.json` (user-level — the right home for the key):

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

A project-scoped `.cursor/mcp.json` gets committed — there, reference an env
var instead: `"Authorization": "Bearer ${env:PLUNGEAI_API_KEY}"` (Cursor
interpolates `${env:…}` in `command`, `args`, `env`, `url`, and `headers`).

## Verify

1. Settings → MCP → `plungeai` shows a green dot with tools listed.
2. In Agent chat: "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

- MCP tools fire in **Agent** and **Plan** modes; **Ask** mode is read-only
  and won't call them.
- Tool calls run behind per-call approval by default. Money-verb PlungeAI
  operations still pause with a structured `needs_approval` outcome even
  under auto-run — relay it, then `plungeai_continue`.
- Tool cap: users report a limit of roughly 40 MCP tools sent to the model
  across all servers (unverified, not in Cursor's current docs). If
  `plungeai_*` tools are missing, disable unused servers or toggle off
  unneeded tools, then reopen the chat.
- After editing `mcp.json`, toggle the server off/on in Settings → MCP (or
  restart Cursor) before debugging anything else.
- Red status / "No tools found" right after install → check auth first: the
  `headers` object must sit *inside* the `plungeai` entry (not beside it)
  and the key must be intact.
- Keep future sessions discovery-first with a one-liner in
  `.cursor/rules/plungeai.mdc`: "PlungeAI: agent ids come from a live
  `plungeai_list_agents` search — never from memory." Rules files are
  committed — never put the key there.

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