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

# Connecting clients

> Every client needs the same two things: the URL https://mcp.plungeai.com/v1 and the header Authorization: Bearer ozk_YOUR_KEY. What differs is where each client keeps its config and what it calls the fields. https://api.plungeai.com/v1/mcp is the same server and works in any of these configs; …


Source: `orchestration/mcp-gateway/integrations.ts`, `install-routes.ts`, `platform/src/worker/install.ts` (the install page on www), `llms-routes.ts`, `docs-routes.ts`, `skill-dist.generated.ts`, `index.ts`; `apps/ocean-skills/skills/plungeai-in-*/SKILL.md` (per-client facts, checked against vendor docs by that skill set), `apps/ocean-skills/skills/plungeai-mcp-setup/SKILL.md`, `apps/ocean-skills/.mcp.json` (the plugin's MCP server), `apps/ocean-skills/scripts/mirror-public.sh`; live `GET /install`, `/install.json`, `/install/:tool`, `/connect/<tool>/SKILL.md` and `https://skills.plungeai.com/index.json` (live-verified 2026-09-24).

Every client needs the same two things: the URL `https://mcp.plungeai.com/v1` and the header `Authorization: Bearer ozk_YOUR_KEY`. What differs is where each client keeps its config and what it calls the fields. `https://api.plungeai.com/v1/mcp` is the same server and works in any of these configs; this chapter uses the canonical URL.

| Client | How it connects | Config lives in | On the install page | Setup skill |
|---|---|---|---|---|
| Claude Code | native HTTP, `claude mcp add` | `~/.claude.json`, or a project `.mcp.json` | command | `/connect/claude-code/SKILL.md` |
| Claude Desktop | `mcp-remote` stdio bridge | `claude_desktop_config.json` | config snippet | `/connect/claude-ai/SKILL.md` |
| claude.ai (web) | skill upload only — no live tools yet | Customize → Skills | steps | `/connect/claude-ai/SKILL.md` |
| Cursor | native HTTP | `~/.cursor/mcp.json` | **Add to Cursor** button | `/connect/cursor/SKILL.md` |
| VS Code (Copilot) | native HTTP | `.vscode/mcp.json` or the user `mcp.json` | **Add to VS Code** button | `/connect/vscode/SKILL.md` |
| Codex CLI | native streamable HTTP | `~/.codex/config.toml` | command (ChatGPT / Codex card) | `/connect/codex/SKILL.md` |
| Gemini CLI | native HTTP (`httpUrl`) | `~/.gemini/settings.json` | — | `/connect/gemini-cli/SKILL.md` |
| OpenCode | native remote (`type: remote`) | `~/.config/opencode/opencode.json` | — | `/connect/opencode/SKILL.md` |
| Windsurf | native HTTP (`serverUrl`) | `~/.codeium/windsurf/mcp_config.json` | config snippet | `/connect/windsurf/SKILL.md` |
| Replit | Integrations → MCP Servers | your Replit account | **Add to Replit** button | `/connect/replit/SKILL.md` |
| Lovable | Connectors → MCP server | your Lovable account | steps | `/connect/lovable/SKILL.md` |
| Bolt.new | Connectors → Custom MCP server | your Bolt account | steps | `/connect/bolt/SKILL.md` |
| v0 | + → MCPs | your v0 account | steps | `/connect/v0/SKILL.md` |

Setup skill paths are on `https://mcp.plungeai.com` (for example `https://mcp.plungeai.com/connect/cursor/SKILL.md`); the same skills are on `https://skills.plungeai.com` as `plungeai-in-<tool>` ([3.16](#316-the-skills-catalog)).

## 3.1 Before you start

**Transport.** The server speaks Streamable HTTP (clients call it "http", "remote" or "streamable-http"). A client that can only launch local stdio servers connects through the `mcp-remote` bridge ([3.14](#314-any-other-mcp-client)). A client that can only speak the old SSE transport cannot connect: the server answers `GET` with `405` at once.

**Where the key goes.** Put the literal key only in a user-level config file or the client's secret store. A config file inside a repository should reference an environment variable instead; each section below shows the client's syntax for that. This guide names the variable `PLUNGE_API_KEY`; the setup skills and the install page use `PLUNGEAI_API_KEY`. Any name works as long as your config and your shell agree. Before committing, run the `git grep` check in [2.9](/mcp/authentication#29-keeping-the-key-safe).

**Check the key outside the client first.** If this returns your identity card, the key is good and any remaining problem is in the client config:

```bash
curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_whoami","arguments":{"user_request":"verify my plungeai connection"}}}'
```

**Verify in the client.** The same three checks work everywhere:

1. The client's MCP panel or command shows `plungeai` connected, with tools listed.
2. Ask: *"use plungeai_whoami to confirm my identity"* → an identity card (user id, tier, key label, rate window, server).
3. Ask: *"use plungeai_list_agents to search 'web search'"* → live registry results. This proves the catalog is reachable, not just the key.

**Reload after every edit.** Clients read the tool list when they connect. After changing the config — or after a platform update adds a tool — restart the client or reload its MCP servers before debugging anything else.

**Approvals are server-side.** A client's auto-approve or auto-run setting only skips the client's own confirmation prompt. Outward, irreversible operations (payments, sends) still stop with a `needs_approval` outcome. An agent's staged action continues only after your explicit answer; a trust-fence refusal cannot be continued over MCP at all and runs only from Ocean Studio ([6.6](/mcp/tools#66-the-trust-fence--needs-approval)).

**Tool caps.** Some clients limit how many tools they send to the model across all connected servers. PlungeAI adds 22 (fewer with a fenced key). If `plungeai_*` tools are missing, turn off tools or servers you do not use.

## 3.2 Claude Code

Terminal one-liner (the key expands from your shell and is stored in `~/.claude.json`):

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

- `--scope user`: every project. Default `local`: this project only. Both live in `~/.claude.json`.
- Never `--scope project` with a literal key — it writes the key into the repo's `.mcp.json`.

Team-shared project file (safe to commit — it holds no key; each developer exports `PLUNGE_API_KEY` before starting Claude Code):

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

**Verify:** `claude mcp list` (or `/mcp` in a session) shows `plungeai` connected; then the three checks in [3.1](#31-before-you-start).

**Quirks:**

- `401` (`No valid authentication provided…`): the header never arrived or the key is wrong. Re-check the header field in `~/.claude.json` / `.mcp.json` rather than the key value, and look for whitespace pasted into the key.
- Connected but no `plungeai_*` tools: restart the session after any config edit.
- Long CNL workflows: ask for them to run in the background (`mode: "async"` + `plungeai_get_workflow_status`) rather than one long synchronous call.
- Type `/plungeai` and pick `/plungeai:plungeai (MCP)` to start from the server's prompt; run it bare and give your request in the next message ([Prompts & resources](/mcp/prompts-resources)).
- **Skills for Claude Code** (conventions, CNL authoring): working today, download a zip from `https://skills.plungeai.com` (or `https://mcp.plungeai.com/skill.zip`, the workflow-authoring skill) and unzip it into `.claude/skills/` or `~/.claude/skills/`. When the public repo is published: `claude plugin marketplace add PlungeAI/plungeai-agent-skills`, then `claude plugin install plungeai@plungeai` ([3.16](#316-the-skills-catalog)). The plugin also registers its own `plungeai` MCP server (header `Bearer ${PLUNGEAI_API_KEY}`), so install it *instead of* `claude mcp add`, not in addition, and export `PLUNGEAI_API_KEY`. If you already added the server by hand, keep only one of the two.

## 3.3 Claude.ai and Claude Desktop

Two surfaces, two capabilities:

| Surface | What it gets |
|---|---|
| **Claude Desktop** | the live `plungeai_*` tools, through the `mcp-remote` bridge |
| **claude.ai (web)** | a PlungeAI **skill** only: Claude learns PlungeAI's conventions and writes paste-ready CNL workflows for Studio, but has no live tool calls |

Why a bridge: the custom-connector UI in claude.ai and Desktop (Settings → Connectors → Add custom connector) authenticates only through OAuth and has no field for a bearer header, and the PlungeAI MCP server has no OAuth yet.

**Claude Desktop.** Needs Node.js (the bridge runs through `npx`). Open Settings → Developer → **Edit Config**; the file is `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS and `%APPDATA%\Claude\claude_desktop_config.json` on Windows. Merge:

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

Quit Claude Desktop completely and start it again; the file is read only at start.

**claude.ai web.** First turn on **Settings → Capabilities → Code execution and file creation** (required for any custom skill). Then **Customize → Skills → + → Upload a skill** and upload `https://mcp.plungeai.com/skill.zip` (the workflow-authoring skill; start with this one), or a single-skill zip from `https://skills.plungeai.com` (`https://skills.plungeai.com/<name>.zip`), one skill per upload. Skill names may not contain the reserved word "claude", so `plungeai-in-claude-ai` and `plungeai-in-claude-code` cannot be uploaded to claude.ai. The all-in-one `plungeai-agent-skills.zip` holds all 32 skills; it is for unzipping into a skills folder, not for upload.

**Verify:** Desktop — the three checks in [3.1](#31-before-you-start). claude.ai web has no live call to check; ask Claude to draft a PlungeAI CNL workflow to confirm the skill loaded.

**Quirks:**

- **Windows:** Desktop does not escape spaces inside `args`. If the bridge answers `401` only on Windows, use `"--header", "Authorization:${AUTH_HEADER}"` and add `"env": { "AUTH_HEADER": "Bearer ozk_YOUR_KEY" }` to the same entry.
- Logs: `~/Library/Logs/Claude/mcp*.log` (macOS), `%APPDATA%\Claude\logs` (Windows). Read them before editing the config again.
- The bridge is an `npx` process; a cold start takes a few seconds. If the tools never appear, wait, then check the logs.
- Claude Desktop caps a single tool call at about 4 minutes. For anything longer, ask for it to run "in the background": you get an execution id at once and ask for the status or result later.
- `401` through the bridge with a key that looks right: whitespace, or a missing `ozk_` prefix — paste the key again.

## 3.4 Cursor

**One click.** Open `https://www.plungeai.com/install`, type your `ozk_` key into the box at the top, then click **Add to Cursor** and confirm Cursor's install dialog. The link is rewritten in your browser to include the header. Clicked without a key, the server installs with no header (it shows red, `401`) and you add the `headers` block by hand.

**By hand**, in `~/.cursor/mcp.json` (user-level — the right place for a literal key):

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

A project `.cursor/mcp.json` gets committed; there, reference a variable: `"Authorization": "Bearer ${env:PLUNGE_API_KEY}"` (Cursor interpolates `${env:…}` in `command`, `args`, `env`, `url` and `headers`).

**Verify:** Settings → MCP → `plungeai` has a green dot and lists tools; then the checks in [3.1](#31-before-you-start) in Agent chat.

**Quirks:**

- MCP tools run in **Agent** and **Plan** modes. **Ask** mode is read-only and does not call them.
- Tool calls ask for approval per call by default.
- Red status or "No tools found" right after install: check auth first — the `headers` object must sit *inside* the `plungeai` entry, and the key must be intact.
- After editing `mcp.json`, toggle the server off and on in Settings → MCP (or restart Cursor).
- The `plungeai-in-cursor` skill notes a reported cap of roughly 40 MCP tools across all servers (not in Cursor's current docs). If `plungeai_*` tools are missing, turn off unused servers or tools and reopen the chat.
- Keep sessions discovery-first with a line 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.

## 3.5 VS Code (GitHub Copilot)

**From a terminal** (simplest):

```bash
code --add-mcp '{"name":"plungeai","type":"http","url":"https://mcp.plungeai.com/v1","headers":{"Authorization":"Bearer ozk_YOUR_KEY"}}'
```

In PowerShell or cmd, double-quote the JSON and escape the inner quotes with `\"`.

**One click:** type your key into the box on `https://www.plungeai.com/install`, click **Add to VS Code**, confirm the MCP dialog.

**Committed-safe workspace file** `.vscode/mcp.json`: the `inputs` block makes VS Code prompt for the key once and store it encrypted, so the file never holds the key:

```json
{
  "inputs": [
    {
      "id": "plungeai-key",
      "type": "promptString",
      "password": true,
      "description": "PlungeAI ozk_ key"
    }
  ],
  "servers": {
    "plungeai": {
      "type": "http",
      "url": "https://mcp.plungeai.com/v1",
      "headers": { "Authorization": "Bearer ${input:plungeai-key}" }
    }
  }
}
```

Machine-wide instead: **MCP: Open User Configuration**, or **MCP: Add Server** with the user scope — same fields, outside any repo.

**Verify:** **MCP: List Servers** shows `plungeai` running and the chat Tools picker lists `plungeai_*`; then the checks in [3.1](#31-before-you-start) in Copilot agent chat.

**Quirks:**

- MCP tools run in **agent mode** (Chat view → mode picker → Agent).
- At most **128 tools per chat request** across all sources. Over the limit, deselect servers or tools in the Tools picker, or let `github.copilot.chat.virtualTools.threshold` group tools beyond the threshold.
- Mistyped key: **MCP: List Servers** → `plungeai` → **Show Output** shows the `401`. Restart the server from the same menu; if it does not ask for the stored input again, remove and re-add the server.
- Locked-down setups: `chat.mcp.access` decides which MCP servers may run, and organisation policies (`ChatAllowedMcpServers`, `ChatDeniedMcpServers`, `ChatAllowManagedMcpServersOnly`) can allow- or deny-list servers. A missing MCP section in settings usually means one of these.
- VS Code asks you to confirm you trust a server before its first start, except when it is started directly from `mcp.json`.

## 3.6 Codex CLI (and ChatGPT)

Codex CLI supports remote streamable-HTTP servers natively. In `~/.codex/config.toml`:

```toml
[mcp_servers.plungeai]
url = "https://mcp.plungeai.com/v1"
bearer_token_env_var = "PLUNGE_API_KEY"
```

Export `PLUNGE_API_KEY` in your shell profile; the file holds no key. Or add it from the terminal:

```bash
codex mcp add plungeai --url https://mcp.plungeai.com/v1 --bearer-token-env-var PLUNGE_API_KEY
codex mcp list
```

A static header also works, in the user-level file only: `http_headers = { Authorization = "Bearer ozk_YOUR_KEY" }`.

Fallback for a build without native `url` support — the `mcp-remote` bridge:

```toml
[mcp_servers.plungeai]
command = "npx"
args = ["-y", "mcp-remote", "https://mcp.plungeai.com/v1",
        "--header", "Authorization: Bearer ozk_YOUR_KEY"]
startup_timeout_sec = 30
```

`startup_timeout_sec` defaults to 10 seconds; an `npx` cold start can exceed it, and then the tools never appear with no useful error. If the bridge answers `401`, Codex is splitting the spaces inside `args` — use the native form above.

**Verify:** `codex mcp list` shows `plungeai` (or `/mcp` in the TUI shows it connected); then the checks in [3.1](#31-before-you-start).

**Quirks:**

- `config.toml` is TOML: no braces around the table, no trailing commas, and the header is exactly `[mcp_servers.plungeai]` (underscore).
- `tool_timeout_sec` defaults to 60 seconds. Run long workflows with `mode: "async"` and poll `plungeai_get_workflow_status`.
- `codex mcp get plungeai` and `codex mcp remove plungeai` manage the entry; `enabled = false` turns it off without deleting it.
- **ChatGPT (web):** not supported yet. ChatGPT connectors need OAuth, and PlungeAI OAuth is in progress. ChatGPT users connect through Codex CLI for now.

## 3.7 Gemini CLI

Merge into `~/.gemini/settings.json` (user-level):

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

**The key is `httpUrl`, not `url`.** Gemini CLI uses `url` for SSE servers; this server answers an SSE-style `GET` with `405`, so a `url` entry never connects. This is the most common mistake with this client.

If your build has no `httpUrl`, bridge instead:

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

A project `.gemini/settings.json` gets committed — keep the literal key in the user-level file.

**Verify:** `/mcp` in the CLI lists `plungeai` with its tools; then the checks in [3.1](#31-before-you-start).

**Quirks:**

- `/mcp reload` reconnects the servers and re-reads their tools after a settings edit. (`/mcp refresh` exists on some builds but has had reload bugs upstream.) If neither picks up the change, restart the CLI.
- Tool calls ask for confirmation by default; `"trust": true` on the server entry skips that prompt. Platform approvals still pause.
- A setup that used to work and now shows no tools usually means the key was revoked or expired — run the `curl` check in [3.1](#31-before-you-start) before touching the config.
- A `GEMINI.md` line such as "PlungeAI agent ids come from a live `plungeai_list_agents` search — never from memory" keeps sessions discovery-first. Context files are committed; never put the key there.

## 3.8 OpenCode

Merge into `~/.config/opencode/opencode.json` (user-level) or the project's `opencode.json`:

```json
{
  "mcp": {
    "plungeai": {
      "type": "remote",
      "url": "https://mcp.plungeai.com/v1",
      "headers": { "Authorization": "Bearer ozk_YOUR_KEY" }
    }
  }
}
```

The top-level key is `mcp` (not `mcpServers`), and a remote server needs `"type": "remote"`. In a committed project file, use variable substitution: `"Authorization": "Bearer {env:PLUNGE_API_KEY}"` (`{file:path}` also exists, for a key file).

**Verify:** the checks in [3.1](#31-before-you-start).

**Quirks:**

- The project config merges over the user config. If tools behave oddly, check whether a committed `opencode.json` (or `.jsonc`) redefines `mcp.plungeai`, for example with `"enabled": false`.
- `{env:…}` is resolved at startup: export the variable before launching OpenCode, or the header goes out empty and you get `401`.
- MCP servers connect at startup; restart the session after any config edit.
- OpenCode reads `AGENTS.md` — the place for a discovery-first reminder. It is committed; never put the key in it.

## 3.9 Windsurf

Windsurf has no install-page button; it is configured by file. Merge into `~/.codeium/windsurf/mcp_config.json` (user-level), then refresh the MCP servers in Cascade's MCP panel or restart Windsurf:

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

`serverUrl` is the documented key for remote servers (Windsurf also accepts `url`, but its examples use `serverUrl`). Older stdio-only builds use the `mcp-remote` bridge, with the same `command`/`args` block as in [3.7](#37-gemini-cli).

**Verify:** Cascade's MCP panel shows `plungeai` with tools after a refresh; then the checks in [3.1](#31-before-you-start) in Cascade.

**Quirks:**

- Config edits are not hot-reloaded: refresh the MCP panel (or restart) after every change.
- Cascade has a limit of roughly 100 tools across all servers. If `plungeai_*` tools are missing, turn off unused servers and refresh.
- Discovery-first rules go in `.windsurf/rules/*.md` (the older `.windsurfrules` is still read) or `~/.codeium/windsurf/memories/global_rules.md`. Rules files are committed; never put the key there.

## 3.10 Replit

Replit's MCP integration is for **Replit Agent while it builds**. Apps the Agent ships call the One API (`https://api.plungeai.com`) with their own key in Replit Secrets.

**One click:** type your key into the box on `https://www.plungeai.com/install`, then click **Add to Replit**; the integration is imported with its `Authorization` header. Clicked without a key, add the header afterwards under the integration's **Advanced settings**.

**By hand:** Integrations → **MCP Servers** → **+ Add MCP server** → Display name `PlungeAI`, Server URL `https://mcp.plungeai.com/v1`, then **Advanced settings** → custom header `Authorization` = `Bearer ozk_YOUR_KEY`.

The integration is account-level: the Agent gets the `plungeai_*` tools in all your projects.

**Verify:** ask the Agent *"use plungeai_whoami to confirm my identity"*, then *"use plungeai_list_agents to search 'web search'"*.

**Quirks:**

- Two key locations, never mixed: the integration's header (for the Agent) and **Replit Secrets** (for your Repl's own code). Never put the key in source files, `.replit` or `replit.nix`.
- An app that works in the workspace but answers `401` after deploy: the deployment's secrets are missing the key.
- A tool that requires confirmation prompts before it runs; platform approvals still pause regardless.
- The usual split when you ask the Agent to "build an app that uses PlungeAI": it uses MCP to find and test the right agent, then writes app code that calls the One API with the key from Replit Secrets.

## 3.11 Lovable

Two connectors, two purposes.

**Chat connector (any plan).** Connectors → **+** → **MCP server** → Server name `PlungeAI`, Server URL `https://mcp.plungeai.com/v1`, Authentication → bearer token / API key → paste your `ozk_` key. Lovable's chat now has the `plungeai_*` tools while it builds.

- Chat connectors are **personal**: each workspace member connects the server with their own key.
- They are **build-time only** and never part of the published app.
- Workspace admins can switch custom MCP servers off for everyone (Connectors → Admin settings → Chat connectors → "Custom MCP"). A member who cannot find "MCP server" in the picker is hitting that switch.

**App connector (workspace admin).** So that apps built in Lovable call PlungeAI in production, an admin creates a custom connector for the One API. Connectors → **+** → **Custom connector**:

| Field | Value |
|---|---|
| Display name | `PlungeAI` |
| Category | Development |
| Documentation URL | `https://www.plungeai.com/docs/one-api` |
| Authentication method | Bearer token |
| API base URL | `https://api.plungeai.com` |
| Test request | `GET /v1/agents` |

Members connect it to their apps with their own key; Lovable checks the key against the test request (green check = valid) and attaches it to every One API call the app makes, so generated code must never add its own `Authorization` header. The full admin pack, including the agent knowledge to attach to the connector, is at `https://mcp.plungeai.com/lovable/SETUP.md`.

**Verify:** chat — the checks in [3.1](#31-before-you-start); app connector — the green check when an app is connected.

**Quirks:**

- If generated code contains an `Authorization` header, the connector knowledge was not attached or the connector step was skipped.
- The app connector is admin-only. Non-admins use the chat connector for building and hand `SETUP.md` to their admin.

## 3.12 Bolt.new

Bolt is a hosted builder: no config file, only the connector form. From the Bolt home chatbox: **+** → **Connectors** → **Manage connectors** → **Custom MCP server**:

| Field | Value |
|---|---|
| Name | `PlungeAI` |
| URL | `https://mcp.plungeai.com/v1` |
| Transport type | `HTTP` |
| Authentication | **API key** → paste your `ozk_` key (Bolt's "MCP OAuth" option does not work with PlungeAI yet) |

Bolt does not document which header its API-key field sends. The server accepts both `X-API-Key: ozk_…` and `Authorization: Bearer ozk_…`, so the raw key works; confirm with the checks below.

**Verify:** in the builder chat, the checks in [3.1](#31-before-you-start).

**Quirks:**

- **Auto-enable for all projects** turns the connector on in each new project; existing projects enable it from the same Connectors menu.
- Adding a connector turns all its tools on, and the tool list is global — you cannot choose tools per project.
- Tools missing mid-session: in Manage connectors, check the connector is enabled for this project and its tools are on.
- The connector key authenticates the **builder** only. The shipped app needs a server function that holds the key as an environment variable and calls the One API. An app that worked in preview but answers `401` when deployed usually shipped without that variable. The key must never reach the client bundle or a browser `fetch`.
- Long CNL workflows can outlast a builder-chat step: ask for them to run in the background.

## 3.13 v0 (Vercel)

v0 is a hosted builder: no config file, only the MCP form. Open **+** in the prompt form → **MCPs** → add your own server (the project settings page offers the same under **Add MCP**):

| Field | Value |
|---|---|
| Name | `PlungeAI` |
| URL | `https://mcp.plungeai.com/v1` |
| Authentication | **Bearer Token** → paste the raw `ozk_` key (v0 adds the `Bearer ` prefix), or **Custom Headers** → `Authorization` = `Bearer ozk_YOUR_KEY`. If one form answers `401`, try the other. `No Auth` and `OAuth` do not apply. |

Then pick the server's permission mode: **Disabled**, **Ask for Approval (Manual)** or **Always Run (Auto)**. Manual is the sensible default.

**The generated app cannot call MCP.** The builder chat uses MCP; the generated Next.js app calls the One API on the server side only, for example from a Route Handler:

```ts
// app/api/plungeai/route.ts
export async function POST(req: Request) {
  const { prompt, agentId } = await req.json()
  const r = await fetch(`https://api.plungeai.com/v1/agents/${agentId}/execute`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.PLUNGE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ prompt, sync: true }),
  })
  return Response.json(await r.json())
}
```

Keep the key in a Vercel environment variable for every environment that needs it — never in a client component, never prefixed `NEXT_PUBLIC_`. The route is documented at `https://api.plungeai.com/docs#9-agents-plane`.

**Verify:** in the builder chat, the checks in [3.1](#31-before-you-start).

**Quirks:**

- Previews run without the project's environment variables until the project is linked or deployed; a `401` from a preview app does not mean the MCP integration is wrong.
- If generation puts the `fetch` in a `"use client"` component, regenerate with: "PlungeAI calls go through a Route Handler; the key stays server-side."
- Long CNL workflows: ask for them to run in the background rather than one long builder-chat call.

## 3.14 Any other MCP client

1. **Native remote / HTTP support (preferred):** URL `https://mcp.plungeai.com/v1`, header `Authorization: Bearer ozk_YOUR_KEY` (or `X-API-Key: ozk_YOUR_KEY`).
2. **stdio-only client:** bridge with `mcp-remote` (Node 18+):

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

   Clients that split spaces inside `args` (mcp-remote's README names Cursor, Codex CLI and Claude Desktop on Windows): pass `"--header", "Authorization:${AUTH_HEADER}"` plus `"env": { "AUTH_HEADER": "Bearer ozk_YOUR_KEY" }` in the same entry. Raise the client's startup timeout if it has one — an `npx` cold start can exceed it.
3. **SSE-only or OAuth-only client** (ChatGPT web connectors, claude.ai custom connectors): not supported yet. Use the One API instead — every capability is reachable over plain HTTPS (`https://www.plungeai.com/docs/one-api`).

A config written before 2026-09-20 may point at `https://mcp.plungeai.com/mcp`. That path still answers with the same server, so it keeps working; new configs use `/v1`.

## 3.15 One-click installs

**The install page** — `https://www.plungeai.com/install` — has one card per target: Claude Code, claude.ai / Claude Desktop, Cursor, VS Code, Replit, Lovable, Bolt.new, v0, Windsurf, the Ocean CLI and ChatGPT / Codex. Each card lists the steps and, where there is one, a ready config snippet. Type your key into the box at the top first: the **Add to Cursor**, **Add to VS Code** and **Add to Replit** buttons are then rewritten in your browser to carry the `Authorization` header. The page makes no network call with the key; it never leaves the page.

**Deeplink redirects** — `GET /install/:tool` answers `302` to the client's install link, **without** a key (you add the header afterwards). It exists for `cursor`, `vscode` and `replit`; any other tool is `404` (live-verified 2026-09-24):

```bash
curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' https://mcp.plungeai.com/install/cursor
```

| Tool | Link | Payload |
|---|---|---|
| Cursor | `cursor://anysphere.cursor-deeplink/mcp/install?name=plungeai&config=<base64>` | base64 of `{"url":"https://mcp.plungeai.com/v1","headers":{"Authorization":"Bearer ozk_…"}}` |
| VS Code | `vscode:mcp/install?<URL-encoded JSON>` | one object: `{"name":"plungeai","type":"http","url":"https://mcp.plungeai.com/v1","headers":{…}}` |
| Replit | `https://replit.com/integrations?mcp=<base64>` | base64 of `{"displayName":"PlungeAI","baseUrl":"https://mcp.plungeai.com/v1","headers":[{"key":"Authorization","value":"Bearer ozk_…"}]}` |

The `headers` part is present only when the page built the link from a key you typed.

**Machine-readable** — `GET /install.json` has the same data: `name`, `mcp`, `api`, `openapi`, `llms_txt`, `skill`, and `tools[]` with `id`, `name`, `method` (`deeplink` · `snippet` · `guide`), `snippet`, `skill`, `steps[]` and, for the three deeplink tools, `deeplink`:

```bash
curl -s https://mcp.plungeai.com/install.json
```

**Per-client setup skills** — `GET /connect/<tool>/SKILL.md` returns the `plungeai-in-<tool>` skill as Markdown, for the twelve tools `claude-code`, `claude-ai`, `cursor`, `vscode`, `codex`, `gemini-cli`, `opencode`, `windsurf`, `replit`, `lovable`, `bolt`, `v0`. `GET /connect/SKILL.md` is the client-independent `plungeai-mcp-setup` skill. Paste the URL into your client and ask it to follow the steps:

```bash
curl -s https://mcp.plungeai.com/connect/cursor/SKILL.md
```

**Other distribution routes** on the same host (no key needed):

| Route | What it is |
|---|---|
| `/lovable/SETUP.md` | the Lovable connector pack for workspace admins |
| `/skill.zip` | the CNL workflow-authoring skill (`plungeai-workflows`), as a zip |
| `/skill/<file>` | the files of that skill one by one (`SKILL.md`, `examples/*.yaml`, `references/*.md`) |
| `/llms.txt`, `/llms-full.txt` | the same skill as an index and as one bundle, for LLM tools |
| `/docs.md` | this whole guide as one Markdown file, for an agent or skill that should read it (the web page is `/docs`) |

## 3.16 The skills catalog

`https://skills.plungeai.com` is the catalog of PlungeAI skills — instruction packs your AI client loads so it already knows how to set up and use PlungeAI. A skill is not a connection; it complements one. Version 3.1.0 holds 32 skills (live-verified 2026-10-05):

| Group | Skills |
|---|---|
| Start here (4) | `choose-your-plungeai-door`, `plungeai-mcp-setup`, `plungeai-api-setup`, `plungeai-cli-setup` |
| Per client (12) | `plungeai-in-<tool>` for the twelve clients in this chapter |
| Capability (13) | `ocean-cli`, `plungeai-platform`, `plungeai-discovery`, `plungeai-tools-connectors`, `plungeai-agents`, `plungeai-missions`, `plungeai-workflows`, `plungeai-results-traces`, `plungeai-memory`, `plungeai-scheduling`, `plungeai-models`, `plungeai-skills-plugins`, `plungeai-campaigns` |
| Studio kinds (4) | `workflow`: `plungeai-workflows` (listed under Capability); `agent`: `plungeai-agentic-agent`; `bot`: `plungeai-bot-agent`; `campaign`: `plungeai-campaign-agent` |

Each skill is at `https://skills.plungeai.com/<name>/SKILL.md` and `https://skills.plungeai.com/<name>.zip`; all of them are in `https://skills.plungeai.com/plungeai-agent-skills.zip`. `/index.json` lists every skill with its group, `skill_md_url`, `zip_url` and `install_command`; `/llms.txt` is the same for LLM tools:

```bash
curl -s https://skills.plungeai.com/index.json
```

**Install today:** download a zip and unzip it into your client's skills folder — each zip holds one folder named after the skill (Claude Code: `.claude/skills/` or `~/.claude/skills/`; claude.ai: upload one single-skill zip at a time under Customize → Skills, not the two `plungeai-in-claude-*` skills and not the bundle, [3.3](#33-claudeai-and-claude-desktop)).

**Install once the public repository is published.** The catalog also shows one-command installs from `PlungeAI/plungeai-agent-skills`. That repository is not public yet (live check 2026-09-24); these commands work once it is:

```bash
npx skills add PlungeAI/plungeai-agent-skills --all --global             # every skill, user-level
npx skills add PlungeAI/plungeai-agent-skills --skill plungeai-in-cursor # one skill
```

- Claude Code: `/plugin marketplace add PlungeAI/plungeai-agent-skills`, then `/plugin install plungeai@plungeai`. The plugin brings its own `plungeai` MCP server (header `Bearer ${PLUNGEAI_API_KEY}`): use it instead of `claude mcp add`, not next to it ([3.2](#32-claude-code)).
- OpenAI Codex: `$skill-installer PlungeAI/plungeai-agent-skills`.

Which skill matches which chapter of this guide:

| Skill | Chapter |
|---|---|
| `plungeai-mcp-setup` | [Authentication & keys](/mcp/authentication), [Errors, feedback & limits](/mcp/errors-limits) |
| `plungeai-in-<tool>` | this chapter |
| `plungeai-discovery` | [Discovery](/mcp/discovery) |
| `plungeai-tools-connectors` | [Tools](/mcp/tools) |
| `plungeai-agents`, `plungeai-missions` | [Agents & missions](/mcp/agents-missions) |
| `plungeai-workflows` | [Workflows](/mcp/workflows) |
| `plungeai-results-traces` | [Runs, results & follow-ups](/mcp/runs-results) |
| `plungeai-memory` | [Chat, memory & skills](/mcp/chat-memory-skills) |
| `plungeai-scheduling` | [Scheduling](/mcp/scheduling) |
| `plungeai-cli-setup`, `ocean-cli` | [3.17 The Ocean CLI](#317-the-ocean-cli) |

## 3.17 The Ocean CLI

The Ocean CLI (`ocean-cli`) is a terminal client for the same platform, built for scripts, CI and other agents: every capability is a verb with flags (`ocean-cli workflows run <id>`, `ocean-cli missions run`, `ocean-cli executions list`, …), `--json` on every verb and stable exit codes. `ocean-cli login` signs you in through the browser and stores your `ozk_` key (`--no-browser` asks for it at a hidden prompt instead); `ocean-cli whoami` shows the identity behind the key and `ocean-cli doctor` checks connectivity. The bot surface is there too: `workflows permissions|files|inbox|bindings|save-version`, `bot-groups`, `executions steer|files`, `schedules create --at/--ends-at`, `wake`, `triggers webhook|email|hooks` and `missions run --sync`. It is not an MCP client you configure: it calls this server's `/v1` and the One API with the same key. Its npm package `@plungeai/ocean` is not published yet. `ocean-cli --help` (at every level) lists the commands and flags.

## 3.18 When a client won't connect

| Symptom | Cause → fix |
|---|---|
| `401` on every call | Key mistyped, pasted with whitespace, revoked or expired, or the header never reached the server. Run the `curl` check in [3.1](#31-before-you-start); if it works, the problem is the client config. |
| `401` only from one network | The key has an `allowed_ips` fence ([2.5](/mcp/authentication#25-key-fences)). |
| `401` only through the bridge | The client split the spaces in `--header` — use the `AUTH_HEADER` form ([3.14](#314-any-other-mcp-client)). |
| `405` or an immediate connect error | The client is using SSE (`GET`). Use its HTTP setting (Gemini CLI: `httpUrl`), or the bridge. |
| Connected, but no `plungeai_*` tools | The client was not reloaded after the config edit, or its tool cap is full. |
| Fewer tools than this guide lists | The key is fenced to a subset of tools — policy, not a fault ([2.5](/mcp/authentication#25-key-fences)). |
| The bridge never appears or times out | Node.js is missing, or the `npx` cold start exceeded the client's startup timeout. |
| Works for one teammate, not another | Separate keys, separate configs — check each machine. |
| `429` with `Retry-After` | Rate limit for your tier ([2.6](/mcp/authentication#26-tiers-and-rate-limits)). |
| `⏸ NEEDS APPROVAL` over MCP, or `403 refused` / `409 approval_required` from an app calling the One API | The trust fence, not a connection problem — relay it to the user ([Tools](/mcp/tools)). |

More in [Troubleshooting & gotchas](/mcp/troubleshooting).