> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plungeai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting a workflow into PlungeAI — three channels

> Connect once (self-service ozk key from Dashboard → One API → Keys, https://dashboard.plungeai.com):


<!-- sources-of-truth: orchestration/mcp-gateway/tools.ts, orchestration/api-gateway/openapi.ts | last-synced: 2026-09-24 -->
## Channel 1 (preferred): PlungeAI MCP server

Connect once (self-service `ozk_` key from **Dashboard → One API → Keys**,
`https://dashboard.plungeai.com`):

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

Other MCP clients (Claude Desktop, Cursor, …) use the `mcpServers` JSON form:

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

Then the whole loop is tool calls — no copy-paste:

1. `plungeai_list_agents {search: "<capability in plain words>"}` — hybrid semantic search over the live catalog. Take agent ids ONLY from results; fetch a full card with `{agent_id}` before using an unfamiliar agent (cards carry parameters and "Not for → use X instead" redirects).
2. `plungeai_execute_workflow {workflow_yaml: "<draft>", input: "..."}` — test ad-hoc before saving. Use `mode: "async"` + `plungeai_get_workflow_status` for runs longer than ~3 minutes.
3. `plungeai_workflow {action: "create", name, yaml, description}` — the platform re-validates server-side, then saves and syncs live to Studio and peer apps. A refusal lists field-level errors — fix exactly those and retry. **This is your final validation step.**
4. `plungeai_workflow {action: "save_version"}` before big edits; `action: "update"` to iterate.
5. `plungeai_learn {source: "<distilled findings>"}` — save research from this chat as a reusable platform skill.

## Channel 2: paste into Ocean Studio

No MCP server? Produce the final YAML in a fenced block for the user. In Ocean Studio: open (or create) the workflow and switch to the **Code** tab → paste the YAML → the editor offers **Validate YAML Syntax** and **Format YAML** → save. Errors surface inline.

## Channel 3: direct HTTP API (advanced)

Same gateway, raw MCP JSON-RPC over HTTP. Get a self-service `ozk_` key from
**Dashboard → One API → Keys** (`https://dashboard.plungeai.com`).

```bash
# list available tools
curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer ozk_YOUR_KEY" -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# execute an ad-hoc workflow (YAML goes in as a JSON string)
curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer ozk_YOUR_KEY" -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"plungeai_execute_workflow","arguments":{"workflow_yaml":"name: quick\ntasks:\n  - agent: brave-agent\n    prompt: \"{input}\"\n","input":"latest AI news"}}}'
```

Create/save is the same shape with `"name":"plungeai_workflow"`, `"arguments":{"action":"create","name":"…","yaml":"…"}`. `X-API-Key: ozk_YOUR_KEY` works as an alternative header. Rate limits by tier: free 30/min, pro 100/min, enterprise 300/min.