PlungeAI MCP — User Guide

Connect your AI client (Claude Code, Claude Desktop, Cursor, Lovable, Replit…) to the PlungeAI platform, then ask for things in plain language. Your client picks the right tool and runs it on the platform.

See also: API docs · Skills · Install

• Server: https://mcp.plungeai.com/v1
• Your API key: self-service — mint an ozk_ key yourself at Dashboard → One API → Keys (https://dashboard.plungeai.com). For a shared team key, ask the account owner.

Connecting

Claude Code (one command):

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

Claude Code / Cursor / other JSON-configured clients — .mcp.json in a project (or the client's global MCP config), same shape everywhere:

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

Claude Desktop / claude.ai: the custom-connector UI is OAuth-centric and can't set a bearer header, so bridge it with mcp-remote:

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

Other clients: point them at https://mcp.plungeai.com/v1 and set the header Authorization: Bearer YOUR_KEY (some clients accept X-API-Key: YOUR_KEY instead).

Raw HTTP (no client)

No MCP client? It is plain JSON-RPC over Streamable HTTP — initialize, then tools/list, then tools/call:

# stateless Streamable HTTP — no session id needed
curl -s https://mcp.plungeai.com/v1 -H "Authorization: Bearer YOUR_KEY" \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
curl -s https://mcp.plungeai.com/v1 -H "Authorization: Bearer YOUR_KEY" -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
curl -s https://mcp.plungeai.com/v1 -H "Authorization: Bearer YOUR_KEY" -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"plungeai_whoami","arguments":{"user_request":"who am I"}}}'

Treat the key like a password — it identifies you to the platform. It is shown only once at creation. If you need a new one, or think yours has leaked, generate a replacement yourself at Dashboard → One API → Keys (https://dashboard.plungeai.com) and revoke the old one. For a shared team key, ask the account owner instead.

Quick start once connected: in Claude Code, type /plungeai — the platform's one activation prompt. Run it bare and your client asks what you want; give it text (/plungeai research Tesla's Q2) and it goes straight to work. You can also just talk normally — the prompt is a convenience, not a requirement.

One-click installs

The install page at https://mcp.plungeai.com/install generates ready-made setup for Claude Code, claude.ai/Desktop, Cursor, VS Code, Replit, Lovable, Bolt.new, v0, Windsurf, and ChatGPT (pending OAuth). Machine-readable: https://mcp.plungeai.com/install.json. Lovable admins: connector pack at https://mcp.plungeai.com/lovable/SETUP.md.

Each tool also has a thin operating skill at https://mcp.plungeai.com/connect//SKILL.md (replit, cursor, vscode, windsurf, codex, gemini-cli, opencode, lovable, bolt, v0, api) — installable everywhere via npx skills add PlungeAI/plungeai-agent-skills --skill plungeai-<tool>.

From a terminal: the ocean CLI. @plungeai/ocean-cli wraps the same platform — AI chat REPL, workflow run/schedule, ocean whoami, memory, templates, missions — over your ozk_ key and/or Studio session. Install: npm i -g @plungeai/ocean-cli, then ocean auth set-key and ocean --help.

How it works

you type a sentence
   └─ your client reads it and decides which tool to call
        └─ mcp.plungeai.com
             └─ the platform: ~90 active agents, workflow engine, saved workflows

One account, everywhere. A workflow you run here is the same workflow you see in Studio and in the mini app. There is no separate "MCP workspace" — anything you create shows up in the other surfaces immediately.

You don't name tools. Describe what you want. Your client chooses between the 20 available tools and fills in the arguments (the full list is in "Every tool on the server" below).

"My agents" means your workflows. In everyday use your saved workflows are your agents — "show me my agents" lists them. The registry is different: ~90 platform building-block agents (search, finance, documents…) that workflows are made of. Say "agents in the registry" or "what can the platform do" when you mean those.

Every run is visible everywhere. Runs started here appear in Studio's results sidebar and the ops dashboard with your question as the title and the workflow + agents that actually ran as the subtitle — same as runs started in Studio itself.

Nothing runs silently. While a call is working, the server streams live status — which agents are running, which just finished, how much has been written, and a final completion line:

⚙️  Agents working — 5/18 agents complete · ✓ brave-agent · 13 active (tavily-agent, exa-agent…)
✍️  Writing (3,516 chars) — …the agent's answer as it is produced
✅  Complete — 18 agents in 24.6s

Conversational and builder calls narrate themselves too — a follow-up reports whether it continued an open session or loaded the run's stored result, and the workflow builder says when it is generating, validating and saving. A task that runs long reports who is still working (⚙️ harness-agent still working — 45s elapsed…).

Two things worth knowing about that feed:

• It is sent on the MCP progress channel when your client asks for progress, and on the logging channel when it does not — so any client can receive it. Whether it is displayed is up to your client; some render it inline under the running tool, some ignore it entirely. The work and the result are identical either way.
• mode:"async" runs are the exception: they return an id immediately and finish in the background, so there is no live feed. Poll plungeai_get_workflow_status instead.

If a tool seems missing, reconnect your client. Clients read the tool list once, when they connect. After a platform update, restart the client to pick up changes.

30 things to ask

Type these as normal sentences.

Finding what the platform can do

1. "What agents do you have for financial analysis and SEC filings?" Searches ~90 live agent cards semantically. Returns matches with what each is good at and what to use instead.

2. "Show me the full card for sec-agent — what operations does it support?" One agent's complete card: every operation, examples, and its "not for this → use X instead" redirects. Worth doing before using an unfamiliar agent.

3. "What connectors are available?" Slack, Google Calendar, GitHub, Notion, Stripe, Salesforce, HubSpot, Shopify, Linear… Also try personas, experts, skills, models.

4. "Which agent should I use to turn a PDF into markdown?" Describe the capability, not the name — the search is semantic. You'll get markitdown, doc-converter, crawl4ai-agent with the differences spelled out.

Tip: ask for a filtered search, never "list all agents". An unfiltered listing returns the whole catalog — about 135 KB into your context in one go.

The catalog is active-only. Discovery lists only agents that are deployed and callable, and asking to run anything else is refused rather than failing halfway. So take agent names from a search, not from memory or another platform — a name that isn't in the catalog will not run here.

Your own workflows

This is the core of the platform — most of what you'll do day to day is discover, run, and inspect your own saved workflows.

5. "Show me all the workflows in my Finance folder." Your folders (rubrics) and what's in them.

6. "What folders do I have and how many workflows in each?" e.g. Finance 15 · Personal 23 · Technology 11 · Business Strategy 14 · Blockchain 8…

7. "Find my workflow about due diligence." Searches your saved workflows by name and description.

8. "Run the Acquisition Scanner with Adobe as the input." Runs a saved workflow. Most finish in seconds — the engine fans out over agents in parallel.

9. "Show me my workflows in the Finance folder, then run the Acquisition Scanner with Tesla as the input." One request, two steps — your client lists the folder to find the workflow you meant, then executes it with your input.

10. "Show me my Acquisition Scanner workflow — what does it actually do?" Fetches the saved workflow's definition so you can see exactly what it runs (which agents, in what order) before you trust it with real input.

11. "Run my Company Snapshot Research Brief with Apple as the input." Same run-a-saved-workflow pattern as #8 — swap in whichever workflow and company you mean.

One-off runs

12. "Ask llm-agent in one sentence what a Cloudflare Durable Object is." Runs a single agent once, no workflow needed.

13. "Ask your harness agent a quick question: what's notable about Sun Valley, Idaho?" A bounded, one-shot harness-agent question — fast and reliable. Keep goals like this short and specific; open-ended "research everything about X" style goals can run long enough to need checking on later (see Troubleshooting).

14. "Build me a workflow that scans a company for acquisition news and writes a briefing." Generates and saves a real multi-agent workflow from a description, choosing actual registry agents.

15. "What workflow templates are available? Start one from the due-diligence template." A library of ready-made workflows. Starting from one copies it into your account so you can edit it.

16. "Rename my Acquisition Scanner, move it to the Finance folder, and save a version first." Direct edits to your saved workflows — create, update, delete, and versioning so you can roll back. YAML is validated before it saves. Creating a workflow can file it straight into a folder ("…and put it in Finance") — no separate move needed.

Calling one agent directly (typed)

Structured agents are forms, not chats — and your client can fill the form for you. It looks up the agent's contract (its exact typed field list, operations, worked examples, and whether your credentials are connected) and then calls the agent directly. You just ask.

This also means you can interrogate any agent in plain language before using it — "What is the x402 broker for?", "Can I search Amazon and pay with x402? What information do you need from me?" — the answer comes from the agent's live card (what it's good at, what to use instead) and its contract (the exact fields, and whether you're set up to use it).

17. "Give me a five-day weather forecast for Sun Valley, including air quality." Runs weather-agent directly with typed fields — by place name, no coordinates needed. The weather agent implements the full OpenWeather surface: current conditions, hourly/daily forecast, air quality, and more.

18. "Before I use the Gmail agent — what exactly does it need from me, and am I connected?" Fetches the agent's contract: every parameter (typed), its operations, a worked example, and the live credential status for your account ("connected as you@…" / "not connected yet"). Great habit before first use of any unfamiliar agent.

19. "Ask llm-agent, using claude-haiku-4-5, to summarize this paragraph." You can pick the model for a single-agent run. Model names are checked against the live catalog before anything runs — a name that doesn't exist is refused instantly with suggestions, never a hang. ("What models are available?" lists them.)

Results and follow-ups

20. "Show me the result of that last run." Fetches the output.

21. "Show me the full result for that specific task, not just the summary." Pass the task_id from one branch of a workflow to get that part's complete output, instead of only the top-level final result. You don't have to guess the ids: a multi-task result ends with a "Steps in this run" index — each step's task id and the agent that ran it — so any step is one ask away. Conversational runs come back with the full conversation thread, not just the last message.

22. "Is that still running?" Status, duration, which task it's on.

23. "Show me my last 10 executions." Your run history with status and timing.

24. "Now do the same analysis but focus on the competitive landscape." A follow-up against a finished run — it keeps the context instead of starting over.

25. "Yes, go ahead" / "Use the second option" Answers a run that paused to ask you something.

Payments

26. "Check my x402 wallet balance, then use the broker to find and buy access to a weather API." The wallet shows your balance and the price; the broker handles discovery and asks your approval before it spends anything.

27. "Use the x402 broker to find StablePhone and place a call to [phone number]." The broker discovers and pays for the calling service (asking your approval first), then places the call — check on it afterward with your x402 wallet.

When a run pauses to ask you something

Some agents stop instead of finishing — always before spending money, and sometimes to ask a question ("which wallet?", "what should the call say?"). Your client will relay it and wait for you:

1. The run comes back with ⏸ AWAITING USER APPROVAL (a staged action + its cost) or ⏸ AWAITING USER (a question). Nothing has been executed yet.
2. Your client asks you to decide. Reply naturally — "yes"/"approve" to proceed, "no" or any normal answer to change course. It is instructed to never approve on its own.
3. On approve, the held action executes exactly once (a stale or repeated approve is harmless — it just answers "nothing awaiting approval", it can never double-pay).

Long-running (async) runs surface pending approvals too — checking the run's status reports them, so a paused background run is never invisible.

A structured tool you call directly (plungeai_execute_tool) is fenced the same way: an outward, irreversible operation — send, pay, transfer, buy, withdraw — comes back ⏸ NEEDS APPROVAL with nothing executed, and only an interactive session (Ocean Studio, where a human can approve) can run it. Unattended, it never spends.

Scheduling, memory, identity

28. "Run the S&P 500 weekly performance analysis every Monday at 7am." Creates a cron schedule. Also: "what do I have scheduled?"

Any active registry agent (or a saved query) is schedulable the same way — the platform wraps it into a saved, visible workflow named "Scheduled: " and schedules that, so every run lands in your normal execution history. A job's run history shows a real execution id per run (fetch any of them like any other result) and an error column, and "run it now" reports the run's actual outcome — not just "triggered". Deleting a job stops it but keeps its run history readable; a deleted job refuses run-now, updates, pause, and resume. Scheduling an unknown or inactive agent is refused at create time, before anything is saved.

29. "What do you remember about Circle's acquisitions?" Long-term memory across runs — facts missions have written down.

Also: "Remember that our fiscal year ends in June." Writes a durable memory — the same store recall reads, and the same mechanism Studio's harness uses — so every later run knows it. Past-run history is deliberately separate from memory: ask "find my past runs about Tesla" or "show me that run" to search and read the run journal.

30. "Who am I, what tier am I on, and how much of my rate limit have I used?" Your identity, and your current usage window.

Bonus — start a plan conversation: "Let's design a due-diligence workflow together" keeps a persistent thread and can save the result as a workflow.

Every tool on the server

What your client sees when it connects — the same 20 tools and descriptions Claude Code shows under /mcp. You never call these by name; this is the reference for what the server can handle.

There is also one prompt, /plungeai — activates the platform with everything above and an optional free-form request.

Markdown by default, JSON on request. Results come back as Markdown — the format an AI reads best. If your client needs machine-parseable output instead, add format: "json" to a result-bearing tool (plungeai_whoami, the list/discovery tools, plungeai_get_result, plungeai_executions, and the execute/contract tools): the reply's text becomes a JSON document and the same object is attached as structuredContent. Leave format off and nothing changes.

You never get a bare error — you get feedback

When something can't run, the platform doesn't fail — it answers with a status that says exactly what's missing and how to fix it. Your client reads these itself and usually self-corrects; this table is so you know what's happening:

One thing worth knowing about refusals: a refusal is not a run. If the platform stops you before dispatch (missing field, missing connection, unknown agent or model), no execution is created — nothing half-happens, and your history stays clean. This now covers looking up a result or workflow by an id that doesn't exist: you get a needs_input answer that names the id, never a bare "not found".

Two more guarantees (shipped 2026-08-02):

• Limits are told to you, never silently applied. Every search engine declares its maximum query length on its card (Serper 2048 characters, Brave 400, Tavily 400). Send more and you get a needs_input answer with the exact limit and your current length — your input is never truncated behind your back.
• Provider failures surface in seconds, with the real reason. A model call that dies upstream no longer hides behind a minutes-long "streaming timeout" — the actual provider error comes back immediately.

And one convenience: if you send plain prose to a tool whose form has exactly one required field (like a report generator's content), the platform fills that field with your prose and tells you it did so in a warning — visible mapping, never guessing.

Your key and its limits

Your key is your identity on the platform. Everything you can see or run is scoped to the account it belongs to — you see what that account owns, never the whole system.

Only tool calls count against these. Ask "how much of my rate limit have I used?" any time.

Your key may be restricted. Depending on how it was issued it can be limited to:

• specific network locations — used from anywhere else it won't authenticate
• specific tools — the others won't appear in your client's tool list at all

If something you expect is missing or refused, that's why. Restrictions are set when the key is minted — self-service keys default to unrestricted; for a fenced team key, ask the account owner who issued it.

Gotchas worth knowing

These are real failures, not hypotheticals.

"Category" and "folder" are different things. Your folders (Finance, Personal…) hold your workflows. Categories are the global agent taxonomy, and the finance one is called financials, not finance — asking for category finance returns zero results. Say "agents for financial analysis" and let the semantic search work.

Results need the execution id, not the workflow id. A workflow id identifies the recipe; each run gets its own execution id. If a result lookup comes back empty, ask "show me my recent executions" first and use that id.

Don't ask for "all agents". An unfiltered listing is large (~135 KB). Always filter by search term, category, or kind. Everything the catalog lists is live and callable — and names from outside it (memory, another platform, a guess) are refused, so when in doubt, search first.

Some agents are forms, not chats. Agents like markitdown, weather-agent, or the Gmail agent take specific fields (a URL, coordinates, a message id) rather than a sentence. Your client handles this itself now: it fetches the agent's exact form (the contract — every field, typed, with a worked example) and fills it in before running. If something is still missing, the answer names the exact fields and shows the form — it never comes back as a bare error, so "do what it suggests" is always enough.

Writing workflow YAML by hand? Quote your colons. A value like prompt: DD: memo breaks YAML — write prompt: "DD: memo", or put long text in a block (prompt: |). The top-level workflow: wrapper is optional — bare name: + tasks: at the top level is accepted and wrapped for you. Easier still: describe the goal and let "build me a workflow that…" write the YAML for you. On an llm-agent task, don't set provider: google — the agent accepts gemini / anthropic / … and refuses google; omit provider to use its default model.

"Needs a connected account" means exactly that. Google, Microsoft and similar agents act as you, so they need your account connected once in Studio → Connectors. The platform checks this before running anything: if the connection is missing (or expired), you get told exactly which service to connect and where — no run is started, nothing half-happens. The same goes for bring-your-own-key agents (wallets, private APIs): save your key once in Studio and every surface can use it. Asking your client "what does this agent need?" shows the live status — "connected as you@…" or "not connected yet".

Broad questions about the platform's own structure can be slow. Something like "what are all the categories and how many agents in each?" makes your client fetch agent cards one at a time — that took 28 seconds once. Ask a narrower question.

Background runs return immediately. A long workflow answers with an execution id, not a result. That's normal — ask for the result once it's finished.

A quiet client is not a stalled run. If you see no live status while something takes a while, the run is still fine — some clients simply don't display the progress channel. Two ways to tell: the result arrives normally when the call ends, and the run is visible in Studio's sidebar the whole time it is executing.

Results are already formatted — ask for them "in full". Everything the server returns is finished markdown (tables, headings, links), including a step index for multi-step runs and the whole conversation thread for runs you have followed up on. Chat clients sometimes summarize long answers on their own; adding "show it verbatim, don't summarize" stops that. Studio, the mini app and the CLI render it directly.

A company name works better than a bare ticker fragment. Financial agents resolve entities from your wording ("latest annual revenue for ticker CRCL", "Apple insider trading Form 4"). If a prompt is ambiguous the answer lists what it tried and asks for the company, ticker or CIK — pass one of those and it resolves.

Free-tier data providers run out. Market-data agents on a free plan exhaust their daily quota; you then get an honest "daily call limit reached on the current plan" rather than a broken-looking error. Retry later, upgrade the key, or use an agent that reads the same numbers from filings.

Claude Desktop caps a single tool call at ~4 minutes. For anything longer, ask for it to run "in the background" — you get an execution id immediately, and you can ask for status or the result any time after.

Troubleshooting

Platform health, no key needed: https://mcp.plungeai.com/health

Need a new key? Self-serve one at Dashboard → One API → Keys (https://dashboard.plungeai.com). Anything else — or a shared team key — goes to the account owner.