---
name: plungeai-in-lovable
description: "Connect Lovable to PlungeAI (Ocean Studio) — a personal chat connector (any plan) so Lovable's chat can operate PlungeAI via MCP while building, and a workspace-admin app connector so shipped apps call the One API in production with attached auth, plus a plungeai_whoami + plungeai_list_agents verify. Use when the user is in Lovable and says connect / install / set up PlungeAI, mentions Connectors or Custom MCP, or a Lovable-built app can't reach PlungeAI. For another builder use its plungeai-in-<tool> skill; for an unlisted but MCP-capable client use plungeai-mcp-setup's generic client config."
---

# PlungeAI in Lovable

Two connectors, two purposes: a **chat connector** (any plan) so Lovable's
chat can operate PlungeAI while building, and an **app connector** (workspace
admin) so the apps users ship call the One API in production.

## Prerequisites

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

## Path A — chat connector (any plan, 2 minutes)

**Connectors → + → MCP server**: Server name `PlungeAI`, Server URL
`https://mcp.plungeai.com/v1`, Authentication → bearer token / API key →
paste the `ozk_` key. Lovable's chat now has the `plungeai_*` tools while
building.

- Chat connectors are **personal**: others in the workspace connect the
  same server themselves, each with their own key.
- They are **build-time only** — never part of the published app. That is
  exactly why Path B exists.
- Workspace admins can switch custom MCP servers off for everyone:
  **Connectors → Admin settings → Chat connectors → "Custom MCP"**. A
  non-admin who can't find "MCP server" in the picker is hitting this
  toggle.

## Path B — app connector (workspace admin)

Creates a reusable custom connector: workspace members connect it to their
apps, each pasting their own key; Lovable then attaches auth to every One
API call the generated app makes.

### 1. Create the connector (Connectors → + → Custom connector)

| Form field | Value |
| --- | --- |
| Display name | PlungeAI |
| Category | Development |
| Documentation URL | https://api.plungeai.com/docs |

### 2. Authentication

| Field | Value |
| --- | --- |
| Authentication method | Bearer token |
| API base URL | https://api.plungeai.com |
| Test request → Method | GET |
| Test request → Path | /v1/agents |

Users paste their own `ozk_` key when they connect an app; Lovable verifies
it against the verification path (green check = valid key).

### 3. Agent knowledge (attach to the connector)

Give the connector these facts so generated code never adds its own
Authorization header (the connector's auth layer already attaches it):

- `GET /v1/agents` lists runnable agents (also the credential-verification
  path); `POST /v1/agents/{id}/execute` runs one, body
  `{ "input": "...", "sync": true }`, returning
  `{ "content": "...", "workflow_id": "...", "task_id": "...", "request_id": "..." }`.
  With `"sync": false` it returns 202 with the same pointer fields — redeem
  via `GET /v1/agents/results/{workflowId}/{taskId}`.
- `GET /v1/discovery/search?q=...` finds the right agent by capability —
  always resolve ids this way, never guess.
- `POST /v1/workflows/execute` runs CNL YAML/JSON; `GET
  /v1/workflows/results/{workflowId}/{taskId}` fetches the deliverable.
- 403 `refused` / 409 `approval_required` are trust fences on money-verb
  tools — surface to the user, never retry.

## Verify

1. Chat: "use plungeai_whoami to confirm my identity" → an identity card.
2. App connector: connecting an app runs Lovable's verification
   (`GET /v1/agents`) → green check.
3. "use plungeai_list_agents to search 'web search'" → live results from
   the active agent catalog.

## Quirks

- Two different auth surfaces: the chat connector's key powers the
  BUILDER; each app's key is pasted by its owner when connecting the app
  connector. Never hardcode any key in the app itself.
- If generated code contains an `Authorization` header, the knowledge
  wasn't attached to the connector, or the connector step was skipped —
  re-check step 3; the connector's own auth layer is the only place
  credentials belong.
- The app connector is workspace-admin gated; non-admins use Path A for
  building and hand the admin this file for Path B.

## Where next

- Route-by-route API manual (agents, tools, workflows, discovery, traces): **plungeai-api-setup**.
- Operating the `plungeai_*` tools in chat: **plungeai-mcp-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**.