# Plunder & Riffle Meme Engine: for agents

Memes, ads, talk-show videos, 1-minute takes, product pushes, two-step outreach drafts and MP4s. Every generator returns a preview page first; a human approves before an MP4 or a post.

## Connect

Get a key at https://www.plunderandriffle.com/hub?section=api-key. Label it `agent:<who>` (`agent:grok`, `agent:codex`…): one key per agent, so each has its own credit balance (its budget) and can be narrowed or revoked alone. New keys can read and generate but cannot post; tick "Can publish" (`mcp:publish`) only for an agent the human trusts to post as them.

The server: `https://bot.plunderandriffle.com/api/mcp`, Streamable HTTP, stateless. Auth: `Authorization: Bearer <key>` or `x-api-key: <key>`. Keep the key in an environment variable (`PLUNDER_KEY` below), never in a prompt.

**Claude Code**
```
claude mcp add --transport http plunder https://bot.plunderandriffle.com/api/mcp --header "Authorization: Bearer $PLUNDER_KEY"
```

**Cursor** (`~/.cursor/mcp.json`)
```json
{ "mcpServers": { "plunder": { "url": "https://bot.plunderandriffle.com/api/mcp", "headers": { "Authorization": "Bearer ${env:PLUNDER_KEY}" } } } }
```

**Gemini CLI** (`~/.gemini/settings.json`)
```json
{ "mcpServers": { "plunder": { "httpUrl": "https://bot.plunderandriffle.com/api/mcp", "headers": { "Authorization": "Bearer $PLUNDER_KEY" } } } }
```

**Claude Desktop, Codex CLI, Windsurf, any stdio-only client**: run the stdio bridge with `PLUNDER_KEY` set. The stdio bridge is the `packages/plunder-mcp` folder of the engine's repo (npm release pending). It forwards stdio JSON-RPC to the remote server and holds no tool logic.
```json
{ "mcpServers": { "plunder": { "command": "node", "args": ["<repo>/packages/plunder-mcp/bin/plunder-mcp.mjs"], "env": { "PLUNDER_KEY": "<key>" } } } }
```
Codex (`~/.codex/config.toml`):
```toml
[mcp_servers.plunder]
command = "node"
args = ["<repo>/packages/plunder-mcp/bin/plunder-mcp.mjs"]
env = { PLUNDER_KEY = "<key>" }
```

**Grok (xAI API)**: pass the server as a remote MCP tool on the Responses API.
```
POST https://api.x.ai/v1/responses
{ "model": "grok-4.7", "input": "…",
  "tools": [{ "type": "mcp", "server_url": "https://bot.plunderandriffle.com/api/mcp", "server_label": "plunder",
              "headers": { "x-api-key": "<key>" }, "allowed_tools": ["get_account", "create_two_step"] }] }
```
`allowed_tools` keeps Grok to the tools its job needs.

**Bankr**: Console → Connections → Custom MCPs → Add, transport Streamable HTTP, URL `https://bot.plunderandriffle.com/api/mcp`, Header auth `Authorization: Bearer {{PLUNDER_KEY}}` (the key saved under Tools → Environment Variables). Reconnect after changing a key's access: Bankr caches the tool list.

**ChatGPT**: add `https://bot.plunderandriffle.com/api/mcp` as a connector and sign in. It uses OAuth (https://bot.plunderandriffle.com/.well-known/oauth-protected-resource), no key to paste.

**Plain HTTP** (GPT Actions, scripts): `GET https://bot.plunderandriffle.com/api/agent/tools` lists the tools; `POST https://bot.plunderandriffle.com/api/agent/tools/<name>` with the arguments as the JSON body runs one, with the same scopes, checks and credits as MCP. Spec: https://bot.plunderandriffle.com/openapi.json.

## How to work

- Every generator returns a temp page preview (`pageUrl`), not a video. Show it to the human. Only after they approve, call `request_mp4`, then poll `get_job_status` every 20–30 s. Never call `publish_clip` without the human's OK.
- Quote the cost before a paid call. Each tool's description gives its credits; `get_account` has the balance.
- Async tools return a `jobId`: poll `get_job_status` with the kind the tool names.
- Send recordings as an https `audio_url`, not base64 (a request is capped at 1 MiB).
- The human sends every message and approves every post. Never promise views, followers or income.

Pricing: 1 credit = $0.01. BYOK (Plunder & Riffle API key + your own provider keys): every API call is 1 credit ($0.01) — one MCP tool call counts once, however many pages it makes — the first 100 each month free; an MP4 is 1 credit ($0.01) when your own Railway render worker is saved (it renders there) or you are full BYOK (every required key saved: LLM, Fish Audio, Giphy, here.now), otherwise the list 25 credits ($0.25) on our servers. Full BYOK pays $0.01 for everything. Without BYOK a key pays each tool's list credits, and x402 pays the list USD price (both run on our provider keys). Failed calls are refunded. Two kinds of call: one on your own keys (BYOK) is 1 credit ($0.01) per call and runs on them, plain HTTP and MCP alike; one on our keys pays that tool's list price. What a BYOK key makes is the owner's to resell — the assets, API access for their own clients, or a branded bot on the engine. A 402 means out of credits: top up, or save your own provider keys (BYOK) — retrying changes nothing. A 403 means this key's own scope (read-only, or no publish permission), not the account: the owner fixes it in /hub.

## Rendering MP4s: our servers or your own worker

- **On our servers:** 25 credits ($0.25) per MP4.
- **On your own render worker:** 1 credit ($0.01) per MP4. Railway bills the server to you directly.

To set up your own worker:
1. Deploy the worker template: https://github.com/davenamovich/plunder-riffle-video-worker-template (one-click Railway deploy: https://railway.com/deploy/_JXizq?referralCode=XO8ClD&utm_medium=integration&utm_source=template&utm_campaign=generic).
2. Save its URL and Record Secret in your hub under **VIP · advanced**: https://www.plunderandriffle.com/hub?section=worker. Never paste the Record Secret into a chat or a prompt.
3. That's all. From then on every MP4 your key requests (`request_mp4`, `render_mp4`, the bot's MP4 buttons) renders on your worker at 1 credit. Nothing changes in how you call the tools.

## Playbooks

### Start: check the key and the menu
_When:_ First call in a session, or when the human asks what this costs or what's left.

1. `get_account`: credits left (-1 = unlimited) and the pricing path (BYOK or list). Free. Each tool's description gives its price: quote it to the human before a paid call.
2. `list_ad_options`: formats, languages and brand keys for the meme tools. Free.

### A meme, carousel, iMessage thread, hot take or confession
_When:_ "Make a meme / carousel / text-thread ad about X", in one or several languages.

1. `list_ad_options` for the `format` ids and languages.
2. `generate_ad_creative` with `format`, and `language` for another language.
3. Ad-ready PNGs (1:1, 4:5, 9:16) of a page already made: `export_ad_assets`.

### Push a product
_When:_ Any product link or product description.

1. `shop` with the link or description (Amazon links too): researched copy plus up to 3 creatives (`creatives`). Copy only: `creatives: []`.

### Turn an offer link into content that points back to it
_When:_ An offer link (a product, service, app, affiliate offer or landing page) to promote with captions, memes or a stick-figure story.

1. `create_funnel` with the link (kept exactly, referral parameters included). Add `format` (captions with an iMessage thread, memes, stickfigures, all, or bestof for a day of content) to build at once, or leave it out to read the offer first.
2. Poll `get_job_status` (kind funnel, jobId = funnelId). `needs-description`: ask the human for a sentence about the offer, then `create_funnel` with `funnel_id` and `description`.
3. Switch format or try another angle with `create_funnel` and `funnel_id` + `format` (+ `variation: next`). No new link needed.
4. Show the preview with `offer.url` as the link underneath. Only after approval call `request_mp4`.
5. From outreach: after a prospect says yes, `continue_two_step` with `funnel: true` builds a share page from THEIR page and an invite link; call it again with the same id (free) for `funnel.message`, a draft the human sends.

### A talk-show video (sit-down, phone demo, best-of, news, ridiculous)
_When:_ "/sitdown about X", a script to read, audio they already have, or a clip to react to.

1. Talk show from a topic, script, audio_url or clip: `create_sitdown`. Interview: add `guest`.
2. ~60 s demo where the posts land on the host's phone: `create_phone_demo`.
3. A best-of page of five generations (reuses the key's recent pages, else makes 2 memes, an iMessage, a slideshow and a top 10 from a `topic`): `get_best_of`. Its `reelLinks` into `create_best_of` give the voiced countdown.
4. 1–5 pages or media links on the sidekick's screen: `create_best_of`.
5. Today's stories, researched live, anchored by Joe: `create_news`. Joe roasting a topic or link: `create_ridiculous`.
6. A recording plus 1–8 page links into a captioned 16:9 video (the best two minutes over screenshots): `create_recut`. It polls as kind sitdown; render it with `request_mp4` and orientation "landscape".
7. A 16:9 Joe presentation with animated charts and diagrams from a topic, a script or a recording: `create_present`. It polls as kind sitdown; render it with `request_mp4` and orientation "landscape".
8. Agents: read top-level `wardrobe`; pass `topicSuffix` into the topic or script. `prlHint.outfitApi` is false — there is no outfit parameter for that hat, outfit and scene.
9. Poll `get_job_status` with the kind the tool returns, show the preview, then `request_mp4` on a yes.

### A ~60-second take, and the same take in other languages
_When:_ "Make a 1-minute video on X", or the human's own recording turned into a video.

1. `create_one_minute` from a topic, the human's own `audio_url`, or a link. Poll `get_job_status` (kind one_minute).
2. Into other languages plus posting copy: `localize_1minute`, from a topic, audio or link in one call, or with the `jobId` of a done take.
3. A recording or a script as meme scenes or caption scenes (not the stick-figure desk): `create_sitdown` with `audio_url` or `script` and `video_style` memes or captions. A verbatim script or mp3 read by a host at the desk: `create_sitdown` or `create_phone_demo`.

### Two-step outreach to one prospect (drafts only)
_When:_ "Pitch this business / person", "write outreach to @handle".

1. Got a list? `find_leads` first (free, up to 10 at a time): it keeps prospects with real material, scores each 0-100, and drops anyone already drafted, declined or opted out. `leads` is highest score first. Parked ones (franchise, closed, bad reviews about the work, no reachable contact) are on `parked`, not in the ranked list.
2. `create_two_step` with ONE prospect (handle, post link, website, or a line about them). It researches them and drafts a 30-second gift meme about their product: script, text DM, caption, meme lines, and the evidence. The DM comes back with outreachGate. A draft under 21/25 (or any mark under 4) is rewritten once, then returned needs_edit with the score breakdown. It refuses to write without real material. Leave offer unset, or pass 24hour with price_usd for a 24-hour run. The same prospect and the same offer returns the saved campaign free. redraft: true writes a new draft.
3. Hand the drafts to the human. The human sends them; you never send. When they say they sent one (or skipped it), `mark_outreach` with `sent` or `skipped`.
4. When the prospect replies, `continue_two_step` with the campaign `id` and their reply. Only a clear yes writes Step 2; a no closes them for good. Someone who asks not to be contacted: `mark_outreach` with `opted_out`.
5. Where things stand: `list_outreach_queue` (filter by status, e.g. `sent` to see who hasn't answered).
6. For a /before that finished: `create_before_scroll` with its `job_id` makes a ~20 second vertical scroll video of its five examples (look feed, phones or chat, a minor Joe track unless `mute`); poll kind `scroll`. The same examples as a ~30 second 1980s retro infomercial (each meme on an old TV, a billboard or a drive-in screen, then in close-up): `create_infomercial` with that `job_id`; poll kind `infomercial`. To film the script: `create_sitdown` with `step1.script`. Agents: read top-level `wardrobe`; pass `topicSuffix` into that topic or script. No outfit parameter. A local trade's `pitchCue` is booked jobs and marketing leaks, never an AI-agent pitch. A one-person pitch page instead: `create_before_pitch` (it returns `wardrobe` too).

### A day of posts for a company (the demo pack)
_When:_ "Show them what a day of posts looks like", an offer to a company, the follow-up to a /2step yes.

1. `create_demo_pack` with the /2step `campaign_id` (or `input`: their site or handle). It plans 5 memes, an iMessage about one of their products, a Top 10 and a slideshow from what we read, makes them, and returns one page with four phones under a short video of Joe walking them through it.
2. Poll `get_job_status` (kind demo_pack). The finished job includes top-level `wardrobe`. Agents: read it; pass `topicSuffix` into Joe's topic or script. Show the human the `pageUrl`; they send it to the company. Nothing is posted.

### More from a finished video
_When:_ "Now make a meme / slideshow / hot take from that one."

1. Ralph's monologue: `create_ridiculous` on the topic, link, or business. Poll `get_job_status` (kind sitdown). A done ridiculous job is read as a sit-down, so its script is the source.
2. `create_followup` with that `job_id` (or a pitch `source_id`, or `context` — the same text) and a `format`. Same subject, same facts, a new post. Show the draft. Nothing is published from the tool itself.
3. Agents: read top-level `wardrobe` on `create_ridiculous` and `create_followup`; pass `topicSuffix` into the topic or script. No outfit parameter. A follow-up keeps the source wardrobe.

### Jobless Joe viral clips (8–10 s, drafts only)
_When:_ "Make me some Joe clips", "surprise me", "10 Joe shorts about the office".

1. `create_joe_clip` with `count` 1, 5 or 10 (or `surprise: true` for the Chaos button). Optional format, pillar, topic, comedy_style, mood, outrageousness. It writes, scores and voices the best `render` (default 1).
2. Poll `get_job_status` (kind joe_clip). Done carries `cards`: show each one's preview, Joe's lines, the score with its reasons, caption, pinned comment and question. The score is a creative check, never a view forecast.
3. Card buttons: `create_joe_clip` again with `from_job_id`, `concept_id` and `action` (regenerate, change_background, change_punchline, funnier, more_outrageous, variations, part2 — part2 writes the next clip in the series from that card's cliffhanger).
4. Film a card the human picked with `request_mp4` (its preview.pageUrl). Never publish without their yes.

### Render and post (human-approved only)
_When:_ The human has seen the preview and said yes.

1. `request_mp4` with the approved `pageUrl`, then poll `get_job_status` (kind mp4) until `mp4Url`. It renders on the human's own render worker when they have one saved (1 credit), otherwise on ours (25 credits); see "Rendering MP4s".
2. Your end clip: `set_outro` with an https MP4 link (up to 60 seconds) plays after every MP4 this key renders. `set_outro` with off: true removes it. Without a link it says whether one is set. `request_mp4` takes `intro: "joe_call"` (Joe calling on a phone to set up the video, opens the video) and `outro_url` (one render's own end clip; null for none).
3. Their phone page: `set_call_page` with the video link (YouTube or a direct .mp4) plays it inside a phone at `shareUrl`, live as soon as it saves. It ends on their button (`cta_text`, `cta_url`); with no link it ends on the make-your-own-phone button, credited to them.
4. Posting is the human's call: return the MP4 link. `publish_clip` posts to X/Telegram as the key's owner and needs the `mcp:publish` scope plus the human's explicit OK for that post.
5. Super agents only: `post_to_socials` posts a finished video (`mediaUrl`) to the networks you name, through the Upload-Post profile the human picked on /agents. It is locked until they pick one, and it needs their explicit OK for each post.
6. Their own affiliate links: `list_my_offers` returns the referral links the human saved on /hub, and `pages`: our page for each partner with their ref on it. Prefer `pages[].url` in a caption (the page explains the partner, then its button is their link). Use links exactly as written; for a service in `missing`, ask them to add it on /hub.

### Manage a brand bot (owner keys)
_When:_ "Turn /submit off on my bot", "add a /recipe command", "talk to the Joe bot".

1. Read and set the bot's menu: `get_bot_commands`, `set_bot_commands`.
2. Saved-prompt commands: `list_bot_skills`, `save_bot_skill`, `delete_bot_skill`.
3. Talk to a branded bot in its own voice: `chat_with_brand`.

### Research a client's brand and seed a campaign from it
_When:_ "Research this brand", "profile this client", "set up a brand default for my key", "seed a campaign from research".

1. `research_brand` with `url` or `notes` (and `brief: true` for campaign fields). Free. Returns `brandProfile` {name, voice, hashtag, token} + `analysisSummary`. If the site blocks the scraper, DuckDuckGo snippets stand in; `evidenceVia` says which.
2. To make this key's default voice: `save_brand_default` with the `brandProfile`. To read the saved default: `get_brand_default`.
3. To create a draft campaign from the research: `create_campaign_from_research` with the `campaign` object from `research_brand { brief: true }`. It copies only sourced fields; unknown ones go in `needs`.

## More

Server card: https://bot.plunderandriffle.com/.well-known/mcp/server-card.json · OpenAPI: https://bot.plunderandriffle.com/openapi.json · Claude skill: https://bot.plunderandriffle.com/skills/plunder/SKILL.md · llms.txt: https://www.plunderandriffle.com/llms.txt
