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

# Prompts & resources

> orchestration/mcp-gateway/server.ts (resource templates, handler wiring), orchestration/mcp-gateway/skill-dist.generated.ts, orchestration/mcp-gateway/llms-routes.ts, MCP SDK 1.29.0 (types.js McpError, shared/protocol.js).


Source: `orchestration/mcp-gateway/prompts.ts` (`handlePromptList`, `handlePromptGet`),
`orchestration/mcp-gateway/resources.ts` (`handleResourceList`, `handleResourceRead`),
`orchestration/mcp-gateway/server.ts` (resource templates, handler wiring),
`orchestration/mcp-gateway/skill-dist.generated.ts`, `orchestration/mcp-gateway/llms-routes.ts`,
MCP SDK 1.29.0 (`types.js` `McpError`, `shared/protocol.js`).

Besides its 22 tools, the server offers **one prompt** and **five resources** plus **three
resource templates**. They are read-only and run nothing, and they work on
`https://mcp.plungeai.com/v1` and on the same server at `https://api.plungeai.com/v1/mcp`. All
content is live: registry listings come from the registry at request time, and workflow and
execution resources are read from your account with an ownership check. There is no static
manifest.

## 12.1 The `/plungeai` prompt

There is exactly one prompt. It activates the whole platform in one step. Earlier recipe prompts
(research pipeline, market research, …) were removed on purpose: they showed up as separate slash
commands and locked the client into one behaviour, when the tools already cover everything
(`prompts.ts`).

| Field | Value |
|---|---|
| `name` | `plungeai` |
| `title` | `PlungeAI` |
| `description` | `PlungeAI MCP` |
| `arguments` | one: `request` (string, **optional**), "What you want to accomplish (optional)" |

**Using it in a client.** Clients list MCP prompts in their slash-command or prompt menu. In
Claude Code the prompt appears as `/plungeai:plungeai (MCP)`: type `/plungeai` to filter the menu
and pick it, or run `/mcp__plungeai__plungeai` directly (the middle part is the server name you
chose in `claude mcp add`). Claude Code splits any text after the command on whitespace, one word
per argument, so only the first word would reach `request`. Run the prompt bare, then type your
request as the next message. Other clients may offer a form field for `request` instead.

- run bare (no `request`): the model is told to ask you what you want to accomplish;
- with `request` set (for example `research Tesla's Q2`, from a client that offers the field): the
  model is told to handle that request now.

The prompt is a convenience, not a requirement. You can always just talk to your client normally.

`prompts/list`:

```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":"prompts/list"}'
```

`prompts/get` returns `description: "PlungeAI MCP"` and one `user` message (type `text`). It runs
nothing, so it is free:

```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":2,"method":"prompts/get","params":{"name":"plungeai","arguments":{"request":"research Tesla'"'"'s Q2"}}}'
```

What the message tells the model:

- It now has the full platform through the `plungeai_*` tools: about 90 active agents, CNL
  workflows, missions, long-term memory and execution history.
- **Discover.** "Show me my agents/workflows" means saved workflows (`plungeai_list_workflows`).
  The registry (`plungeai_list_agents` with a natural-language `search`) is for building blocks.
  Fetch a full card with `agent_id` before first use.
- **Execute.** `plungeai_execute_agent` (one agent, optional `session_id`), `plungeai_execute_workflow`
  (saved `workflow_id` or ad-hoc CNL YAML), `plungeai_run_mission` (bounded autonomous loop with
  memory).
- **Results.** `plungeai_get_result`, `plungeai_get_workflow_status` (poll async runs),
  `plungeai_executions`, and `plungeai_followup` / `plungeai_continue` for finished or paused runs.
- **Approvals.** Relay any "⏸ AWAITING USER APPROVAL" or "⏸ AWAITING USER" block verbatim, never
  approve on its own, then call `plungeai_continue` with `approve: true` or the user's words.
- **Build.** `plungeai_build_workflow` generates and saves a workflow. `plungeai_workflow` is direct
  CRUD. `plungeai_memory` is long-term memory.
- Always pass `user_request`, the user's words verbatim.
- The last line is either `Now handle this request: <request>` (the argument is trimmed) or
  `Ask the user what they want to accomplish.` when `request` is empty or absent.

An unknown prompt name is **rejected** with `-32602`. The SDK prefixes the message with
`MCP error -32602:`:

```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":3,"method":"prompts/get","params":{"name":"research"}}'
```

## 12.2 Resources at a glance

`resources/list` returns five fixed resources (`handleResourceList`):

| URI | `name` | `mimeType` | Returns | Scope |
|---|---|---|---|---|
| `plungeai://agents/list` | PlungeAI Agents | `text/markdown` | the active registry agents, up to 100, as registry Markdown | platform (active agents only) |
| `plungeai://agents/categories` | Agent Categories | `text/markdown` | a category → agent-count table | platform (active agents only) |
| `plungeai://personas/list` | Personas | `text/markdown` | persona cards, up to 100, as registry Markdown | platform |
| `plungeai://workflows/list` | Your Workflows | `text/markdown` | your 50 most recently updated saved workflows | **your account** |
| `plungeai://docs/workflow-authoring` | Workflow Authoring Guide | `text/markdown` | the full CNL workflow-authoring skill bundle | static |

`resources/templates/list` returns three URI templates (`server.ts`) for resources addressed by a
parameter:

| `uriTemplate` | `name` | `mimeType` | Scope |
|---|---|---|---|
| `plungeai://agents/{category}` | Agents by category | `text/markdown` | platform (active agents only) |
| `plungeai://workflows/{id}` | Workflow YAML by id | `text/yaml` | **your account**, ownership-checked |
| `plungeai://executions/{id}` | Execution result by id | `text/markdown` | **your account**, ownership-checked |

The resources and templates carry no `size` or `annotations`. The templates carry no `description`.
Every `resources/read` answers `{ "contents": [ { "uri", "mimeType", "text" } ] }` with one entry.
The server's `resources` capability is `{}`: no `subscribe` and no `listChanged`
([Protocol & transport](/mcp/protocol)).

```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":4,"method":"resources/list"}'
```

```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":5,"method":"resources/templates/list"}'
```

**Resources or tools?** A resource is the same data some tools return, in a form your client can
attach to a conversation without a tool call. For searching and filtering, use the tools:
`plungeai_list_agents` for a semantic search, `plungeai_list_workflows` for folders and search,
`plungeai_get_result` for one task's output ([Discovery](/mcp/discovery),
[Runs, results & follow-ups](/mcp/runs-results)).

## 12.3 `plungeai://agents/list`

The live registry of **active** agents: `kind=agents&status=active&format=md&limit=100`. The
Markdown starts `# Registry search`, then `*<n> results*`. Each agent follows under a
`## Name (id)` heading with its kind, category and status line, its description and a **Good at**
list. On 2026-09-24 the
registry listed **92** active agents (live-verified). The listing is large, about 150 KB, so attach
it only when you really want the whole catalog. For a normal question, a filtered
`plungeai_list_agents` search is far smaller.

```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":6,"method":"resources/read","params":{"uri":"plungeai://agents/list"}}' \
  | cut -c1-1200
```

## 12.4 `plungeai://agents/categories`

Active agents (up to 500) grouped by category into one table, largest first. An agent with no
category counts as `general`:

```
# Agent Categories (<n> agents, live registry)

| Category | Agents |
|:---|---:|
| google-workspace | … |
…

_Read `plungeai://agents/{category}` for the agents in one category._
```

This is the cheap way to answer "what kinds of agents are there". On 2026-09-24 the registry held
92 active agents in 14 categories (live-verified): `google-workspace`, `tools`, `search`,
`microsoft-365`, `ai`, `blockchain`, `communication`, `ecommerce-agents`, `payment`,
`entertainment`, `media`, `financials`, `shopping`, `coding-agents`. Note the finance category is
`financials`, not `finance`.

```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":7,"method":"resources/read","params":{"uri":"plungeai://agents/categories"}}'
```

## 12.5 `plungeai://personas/list`

The persona registry: `kind=personas&format=md&limit=100`, as registry Markdown (a `## Name (id)`
heading per persona, its kind and category, **Good at**). Unlike the agent resources, it has **no** `status:active` filter,
because no persona card carries that tag and the filter would empty the list (`resources.ts`). The
list stops at 100: on 2026-09-24 the registry answered `*100 results*`. For a specific persona,
search with `plungeai_list_agents` `{"kind":"personas","search":"…"}`. A persona id goes on
`plungeai_execute_agent` `persona` or a mission's `persona`
([Agents & missions](/mcp/agents-missions)).

```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":8,"method":"resources/read","params":{"uri":"plungeai://personas/list"}}' \
  | cut -c1-800
```

## 12.6 `plungeai://workflows/list`

**Your workflows**: the 50 most recently updated saved workflows on your account (what users call
"my agents"). One bullet each (bold name, the id as code, then the description) under
`# Your Workflows (<n>)`. With no saved workflows, the text is `_No workflows yet._`. It carries
no folders and no search. For those, use `plungeai_list_workflows`.

```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":9,"method":"resources/read","params":{"uri":"plungeai://workflows/list"}}'
```

## 12.7 `plungeai://docs/workflow-authoring`

The complete CNL workflow-authoring skill as one Markdown document: how to author, validate and
save CNL workflows, with examples. It is a static bundle built into the server and needs no data
access. The content is identical to `GET https://mcp.plungeai.com/llms-full.txt`, which needs no
key (61,309 bytes on 2026-09-24, live-verified). Attach it when you want your client to write CNL
YAML by hand ([Workflows](/mcp/workflows)). The same skill is in the catalog at
`https://skills.plungeai.com`.

```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":10,"method":"resources/read","params":{"uri":"plungeai://docs/workflow-authoring"}}' \
  | cut -c1-600
```

## 12.8 `plungeai://agents/{category}`

The active agents in one category, up to 100, as registry Markdown under
`# Registry search — category=<category>`. The category is passed to the registry as-is, so an
unknown or misspelled category is **not** an error. It returns an empty listing (`*0 results*`).
Take category names from `plungeai://agents/categories`.

```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":11,"method":"resources/read","params":{"uri":"plungeai://agents/financials"}}'
```

## 12.9 `plungeai://workflows/{id}`

The saved CNL YAML of one of **your** workflows, as `text/yaml`. The id is the workflow id from
`plungeai_list_workflows` or `plungeai://workflows/list`. The ownership check comes first: an id
that does not exist and an id owned by someone else get the same `-32002` answer, so you cannot
probe for other accounts' ids. A workflow whose YAML body is missing from storage returns the text
`No YAML content found`.

```bash
# needs one of your workflow ids — not auto-verified
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":12,"method":"resources/read","params":{"uri":"plungeai://workflows/<workflow id>"}}'
```

## 12.10 `plungeai://executions/{id}`

The stored result of one of **your** runs, by **execution id** (not the workflow id,
[Troubleshooting](/mcp/troubleshooting)). It reads the same stores as `plungeai_get_result`:
the stored result, then the final task's output. The document looks like this:

```
# Execution <execution id>

- **Workflow:** `<workflow id>`

## Result

<the run's final output>
```

When there is no output, the Result section says why:

| Run state | `## Result` text |
|---|---|
| failed | `_This run failed: <error message>._` (or `no error was recorded`) |
| no output yet | `_No result stored yet (may still be running)._` |

This resource gives the final result only. For one task's output, the full conversation thread, the
"Steps in this run" index or a paused run's ⏸ block, use `plungeai_get_result`
([Runs, results & follow-ups](/mcp/runs-results)). An unknown id, or one that is not
yours, gets `-32002 Execution not found: <id>`.

```bash
# needs one of your execution ids — not auto-verified
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":13,"method":"resources/read","params":{"uri":"plungeai://executions/<execution id>"}}'
```

## 12.11 Resource errors

`resources/read` answers JSON-RPC errors, not outcomes. The SDK prefixes `McpError` messages with
`MCP error <code>:` (`types.js`).

| Case | `code` | `message` |
|---|---|---|
| URI matches no resource or template | `-32002` | `MCP error -32002: Resource not found: <uri>` |
| `plungeai://workflows/{id}`: unknown or not yours | `-32002` | `MCP error -32002: Workflow not found: <id>` |
| `plungeai://executions/{id}`: unknown or not yours | `-32002` | `MCP error -32002: Execution not found: <id>` |
| The registry answered non-2xx (agent, category and persona resources) | `-32603` | `Registry error <status>` |
| `params.uri` missing or not a string | `-32603` | the SDK's raw schema-validation text (a zod issue list) |

```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":14,"method":"resources/read","params":{"uri":"plungeai://nope"}}'
```

Registry-backed reads time out after 10 seconds. For the full error vocabulary, see
[Errors, feedback & limits](/mcp/errors-limits).