Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

docs(mcp): write every guided prompt out as its ordered tool calls, held to the live catalogs by a test

nirholas563529648fa4
diff --git a/docs/mcp.md b/docs/mcp.md
index a8967c7fe..c64ac98a7 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -1071,7 +1071,7 @@ Each server offers short guided workflows through `prompts/list` and `prompts/ge
| `embed-avatar` | `agentId` | mcp | Paste-ready `<agent-3d>` embed code and a preview |
| `generate-3d` | `prompt` | mcp-3d | Sharpen the prompt, generate, poll, optionally rig, save to your library |
-`prompts/list` on a server is the authoritative list for that server; `/.well-known/mcp.json` and each `server*.json` manifest carry the same lists.
+`prompts/list` on a server is the authoritative list for that server; `/.well-known/mcp.json` and each `server*.json` manifest carry the same lists. Every prompt is written out step by step, as the exact tool and resource calls it drives, under [Use cases](#use-cases).
### Worked example: get a prompt
@@ -1086,6 +1086,257 @@ Every prompt that can move funds ends with the same rules: show the recipient, a
---
+## Use cases
+
+Each guided prompt above, written out as the calls an agent makes, in order. Read a use case top to bottom and you have the workflow: which tool or resource to call, what to show the user, and where the user has to say yes. Resources (`three://...` URIs) are read with `resources/read`, or with the `read_resource` tool on clients without a resource UI. Steps marked **Spends money.** move funds or charge the user; every one of them waits for an explicit yes after showing the amount, the token, the chain and the recipient.
+
+Some prompts run differently depending on the server, because each server publishes a different tool set; those use cases list each server separately. `tests/mcp-use-cases-doc.test.js` renders every prompt against every server's live `tools/list` and fails when a tool named here is gone, when a prompt starts calling a tool this section does not name, or when a prompt has no use case here.
+
+### Get started (`get-started`)
+
+Goal: orient a new user on what the server does, their account and agents, and the best first thing to try.
+
+On `mcp`, `mcp-agent` and `mcp-3d`:
+
+1. `getting_started`: summarize in three lines what this server can do.
+2. `read_resource` on `three://me`: confirm the user is signed in; if not, explain OAuth or an API key from [Dashboard, API keys](https://three.ws/dashboard/api-keys) and stop.
+3. `read_resource` on `three://agents`: list the user's agents by name with their Solana address.
+4. Suggest the single best next guided prompt from the ones this server lists.
+
+On `mcp-bazaar`:
+
+1. `getting_started`: summarize in three lines what this server can do.
+2. `read_resource` on `three://me`: confirm the user is signed in.
+3. Suggest the best next guided prompt: hiring an agent, the marketplace, or x402 services.
+
+### Create an agent (`create-agent`)
+
+Goal: create a new agent with a name, persona and brain model, then give it a body.
+
+On `mcp`:
+
+1. `read_resource` on `three://models`: confirm the chosen model is available, or recommend one free and one paid model with prices.
+2. `identity_check` with the name and description: catch a look-alike of an existing public agent before creating.
+3. Show the name, persona and model, and wait for the go-ahead.
+4. `create_agent`: creates the agent with a custodial Solana wallet. Moves no funds.
+5. `read_resource` on `three://agents/{agentId}`: show the new agent's page URL and Solana address.
+6. `list_my_avatars`, then `attach_avatar_to_agent` with the avatar the user picks.
+7. Next: fund the wallet with the Set up an agent wallet use case on `mcp-agent`, or embed the agent on a site.
+
+### Set up an agent wallet (`setup-wallet`)
+
+Goal: provision, review and fund an agent's Solana wallet, and get notified of transfers.
+
+On `mcp-agent`:
+
+1. `read_resource` on `three://agents/{agentId}/wallet`: is there a wallet yet?
+2. `provision_wallet` with the agent id on mainnet, only if the address is null. Creates a wallet, moves no funds.
+3. `wallet_status`: address, SOL and USDC balances, spending caps.
+4. Walk through the guard settings (daily and per-transaction USD limits, withdraw allowlist, freeze switch), changed on the agent's wallet page.
+5. **Spends money.** The user funds the wallet by sending SOL or USDC on Solana to the address from their own wallet. The agent never sends funds from here.
+6. `resources/subscribe` on `three://agents/{agentId}/wallet`: notified after every transfer in or out.
+
+### Research and trade a token (`trade`)
+
+Goal: research a Solana token, check the agent's balance and limits, then trade it with explicit confirmation.
+
+On `mcp`:
+
+1. `token_snapshot` with the mint: price, liquidity, market cap and holders.
+2. `pumpfun_token_intel` with the mint: creator history and risk flags.
+3. `oracle_coin` with the mint: conviction score and its reasons.
+4. `read_resource` on `three://agents/{agentId}/wallet`: balance, trade limits (per-trade SOL, daily budget, max slippage) and freeze state.
+5. Summarize the risks and the case for and against in five lines.
+6. **Spends money.** Swap execution is not enabled on this server yet, so the user quotes and confirms the swap on the agent's wallet page (`/agents/{agentId}/wallet#trade`). The prompt switches to quoting and executing in MCP once those tools ship.
+
+### Launch a token (`launch-token`)
+
+Goal: launch a token from an agent, with the name, symbol and cost confirmed first.
+
+On `mcp`:
+
+1. `read_resource` on `three://launches`: what this account launched before; flag a repeated name or symbol.
+2. `pumpfun_recent_graduations`: what recently graduated launches have in common.
+3. `read_resource` on `three://agents/{agentId}/wallet`: enough SOL for the launch fee?
+4. Show the name, symbol, description, image, launching wallet and cost, and wait for a yes.
+5. **Spends money.** Launching from MCP is not enabled yet: the user reviews and signs the launch on [/launch](https://three.ws/launch). Then `read_resource` on `three://launches` to confirm it landed.
+
+### Hire an agent for a task (`hire-agent`)
+
+Goal: find an agent or paid service that does the task, compare prices, and hire it with a confirmed, capped spend.
+
+On `mcp-agent` (pays from the agent wallet):
+
+1. `find_services` with the task as the query: the three best matches with price and network, Solana first.
+2. `wallet_status`: the balance and spending caps cover the price.
+3. Show the service, resource URL, exact price and paying wallet, and wait for a yes.
+4. **Spends money.** `pay_and_call` with that resource URL and the maximum price set to the quote, so it refuses to pay more.
+5. Show the result and the payment receipt.
+
+On `mcp`:
+
+1. `read_resource` on `three://marketplace`: agents and services that fit the task, with price, free-trial uses and completion stats.
+2. `call_agent` with the chosen agent and a clear brief.
+3. To pay a priced service from a wallet, continue on `mcp-agent` (above).
+
+On `mcp-bazaar`:
+
+1. `search_services` with the task as the query: the best matches, Solana first.
+2. `get_service` on the pick: exact price, networks and input schema.
+3. To pay and call it, continue on `mcp-agent` (above).
+
+### Sell a skill (`sell-a-skill`)
+
+Goal: price one of an agent's capabilities and publish it as a paid service other agents can call.
+
+On `mcp-agent`:
+
+1. `read_resource` on `three://agents/{agentId}`: its skills and any prices already set.
+2. `read_resource` on `three://marketplace`: what comparable skills and services charge.
+3. `read_resource` on `three://agents/{agentId}/wallet`: which wallet receives the revenue.
+4. Agree on the name, description, USDC price per call, the https endpoint that does the work, and the network (Solana by default).
+5. `monetize_endpoint` with the agent id and those values. Publishing moves no funds; buyers pay per call.
+6. Show the listing URL and how buyers call it.
+
+### Review costs (`review-costs`)
+
+Goal: break down an agent's model, tool and credit spend this month and find the biggest saving.
+
+On `mcp`:
+
+1. `read_resource` on `three://agents/{agentId}/usage`: this month's LLM calls, tokens and cost per model, tool calls per tool, credit balance.
+2. `read_resource` on `three://models`: current prices per million tokens.
+3. `read_resource` on `three://me`: the daily MCP quota and what is left today.
+4. A short table (model, calls, tokens, cost) and the one change that saves the most, with its estimated monthly saving.
+5. If credits are low, point to [/credits](https://three.ws/credits).
+
+### Set up automations (`setup-automations`)
+
+Goal: put an agent on autopilot with conviction watches, copy trading and standing wallet intents, simulated first.
+
+On `mcp`:
+
+1. `read_resource` on `three://agents/{agentId}/intents` and `three://agents/{agentId}/orders`: what is already running.
+2. `read_resource` on `three://agents/{agentId}/wallet`: balance, trade limits and freeze state.
+3. `oracle_watch_status`, then `oracle_arm_watch` in simulate mode, which only logs what it would buy.
+4. **Spends money.** Switching the watch to live mode buys with real SOL from the agent wallet: show the per-trade cap and daily budget and wait for a yes first.
+5. `trader_leaderboard` to pick a leader, then `copy_subscribe` with a per-trade cap and daily budget. Non-custodial: it creates intents the user acts on from the copy dashboard.
+6. Standing wallet intents are created and confirmed on the agent's wallet page.
+7. List every automation now active and how to switch each one off.
+
+### Set up dollar-cost averaging (`setup-dca`)
+
+Goal: plan a recurring buy, check the wallet, and start it with a confirmed permission.
+
+On `mcp`:
+
+1. `read_resource` on `three://agents/{agentId}/dca`: strategies already running and how their last executions went.
+2. `read_resource` on `three://agents/{agentId}/wallet`: balance and limits.
+3. `token_snapshot` on the token to accumulate: liquidity and volatility.
+4. Propose an amount per buy and a period, and show the total committed over three months.
+5. **Spends money.** The user signs the spending permission on [/recurring](https://three.ws/recurring). Then `read_resource` on `three://agents/{agentId}/dca` to confirm it is active.
+
+On `mcp-agent`:
+
+1. `read_resource` on `three://agents/{agentId}/dca`: strategies already running.
+2. `read_resource` on `three://agents/{agentId}/wallet`: balance and limits.
+3. Propose an amount per buy and a period, and show the total committed over three months.
+4. **Spends money.** The user signs the spending permission on [/recurring](https://three.ws/recurring), then the plan is read back to confirm it is active.
+
+### Explore the marketplace (`explore-marketplace`)
+
+Goal: browse paid agent skills and services with prices, free trials and track records.
+
+On `mcp`:
+
+1. `read_resource` on `three://marketplace`.
+2. Group the skills by what they do: the three best per group with price, pricing type and free-trial uses.
+3. Agent-to-agent services by completion count and rating, best first, plus any trials the user still holds.
+4. `call_agent` with a short test request to try one.
+
+On `mcp-agent` and `mcp-bazaar`:
+
+1. `read_resource` on `three://marketplace`.
+2. Group the skills by what they do: the three best per group with price, pricing type and free-trial uses.
+3. Agent-to-agent services by completion count and rating, best first, plus any trials the user still holds.
+4. To hire one, continue with the Hire an agent use case.
+
+### Explore x402 services (`explore-x402`)
+
+Goal: find paid x402 services for a capability, compare prices and networks, and see exactly how to pay.
+
+On `mcp-agent`:
+
+1. `find_services` with the capability as the query: the best matches with price and network, Solana first.
+2. Show the pick with its exact price and wait for a yes.
+3. **Spends money.** `pay_and_call` with its resource URL and the maximum price set to the quote.
+
+On `mcp-bazaar`:
+
+1. `search_services` with the capability as the query (or `browse_services` with no query): the best matches, Solana first.
+2. `get_service` on the pick: exact price, networks, recipient and input schema.
+3. To pay and call it, continue on `mcp-agent`.
+
+On `mcp`:
+
+1. `read_resource` on `three://x402/services`: services matching the capability, Solana first, with price and facilitator.
+2. To pay and call one, continue on `mcp-agent`.
+
+### Earn yield (`earn-yield`)
+
+Goal: put an agent's idle funds to work in lending, with markets compared first.
+
+On `mcp`:
+
+1. `read_resource` on `three://agents/{agentId}/wallet`: what is idle.
+2. `crypto_data` for pool APYs for the assets held, Solana first, plus [/yields](https://three.ws/yields) for the full explorer.
+3. Summarize the two best options and their risks. Lending is not enabled on MCP yet, so no funds move here; once lending tools ship, the prompt adds a quoted, confirmed deposit.
+
+### Trade perpetuals (`perps`)
+
+Goal: research a perpetual futures setup before any position.
+
+On `mcp`:
+
+1. `read_resource` on `three://agents/{agentId}/wallet`: collateral and limits.
+2. `crypto_data` for spot price and recent volatility, and `token_snapshot` for Solana tokens.
+3. Summarize the setup, the liquidation risk at 2x and 5x, and what would invalidate it. Perpetuals are not enabled on MCP yet, so no position opens here; once they ship, the prompt adds a previewed, confirmed order.
+
+### Prediction markets (`predictions`)
+
+Goal: research a prediction-market question and estimate a probability.
+
+On `mcp`:
+
+1. `read_resource` on `three://agents/{agentId}/wallet`: balance and limits.
+2. `crypto_data` for the prices and data behind the question, then a probability estimate with reasoning.
+3. No position is placed here; once prediction-market tools ship, the prompt adds a priced, confirmed position.
+
+### Embed an agent on a website (`embed-avatar`)
+
+Goal: put an agent's live 3D avatar on any site with paste-ready code.
+
+On `mcp`:
+
+1. `read_resource` on `three://agents/{agentId}`: does it have an avatar? If not, `list_my_avatars` and `attach_avatar_to_agent`.
+2. `get_embed_code` with the agent id, at the size and autorotate setting the user wants.
+3. `render_avatar` to preview it in the chat.
+4. The snippet in one code block, where to paste it, and [/embed-doctor](https://three.ws/embed-doctor) to check it once live.
+
+### Generate a 3D model (`generate-3d`)
+
+Goal: turn a text prompt into a textured 3D model, optionally rigged, saved to the user's library.
+
+On `mcp-3d`:
+
+1. `direct_prompt` with the idea: a sharpened, single-subject prompt.
+2. **Spends money.** `text_to_3d` with the prompt, after telling the user the tier's price. Paid per call in USDC over x402 by tier; run operator-funded on a signed-in account.
+3. `generation_status` with the job id until it returns a GLB and an inline viewer.
+4. **Spends money.** `auto_rig_model` if it is a character, so it can be animated. Priced per call over x402; operator-funded on a signed-in account.
+5. `save_avatar` with the GLB URL and a name, then the view link and `read_resource` on `three://assets/{id}` for the saved asset.
+
+---
+
## Rate limits
| Scope | Limit |
diff --git a/tests/mcp-use-cases-doc.test.js b/tests/mcp-use-cases-doc.test.js
new file mode 100644
index 000000000..7cb758c40
--- /dev/null
+++ b/tests/mcp-use-cases-doc.test.js
@@ -0,0 +1,199 @@
+// The "Use cases" section of docs/mcp.md writes every guided prompt
+// (api/_mcp/prompts.js) out as the ordered tool and resource calls it drives.
+// This suite holds that section to the live catalogs so it cannot drift:
+// - every prompt has a use case, and every server that offers a prompt is
+// covered by one of its "On `server`:" blocks;
+// - every tool a block names is published by that server's tools/list, and
+// every three:// resource it names is served there;
+// - a block names exactly the tools the prompt renders on that server, so a
+// prompt that starts calling a new tool forces the doc to follow;
+// - a step that calls a destructive (fund-moving) tool is marked
+// "Spends money.".
+//
+// Inside the numbered steps, backticks hold only tool names (snake_case),
+// three:// resource URIs, and other literals with no snake_case shape (MCP
+// method names, page paths), so the parser below can read them unambiguously.
+
+import { readFileSync } from 'node:fs';
+
+import { describe, it, expect } from 'vitest';
+
+const { PROMPTS, promptsFor, renderPrompt } = await import('../api/_mcp/prompts.js');
+const { matchResource } = await import('../api/_mcp/resources.js');
+const { TOOL_CATALOG: mainCatalog } = await import('../api/_mcp/catalog.js');
+const { TOOL_CATALOG: agentCatalog } = await import('../api/_mcpagent/catalog.js');
+const { TOOL_CATALOG: studioCatalog } = await import('../api/_mcp3d/catalog.js');
+const { TOOL_CATALOG: bazaarCatalog } = await import('../api/_mcpbazaar/catalog.js');
+
+const SERVERS = { mcp: mainCatalog, 'mcp-agent': agentCatalog, 'mcp-3d': studioCatalog, 'mcp-bazaar': bazaarCatalog };
+
+const DOC = readFileSync(new URL('../docs/mcp.md', import.meta.url), 'utf8');
+
+const SPEND_MARK = '**Spends money.**';
+const TOOL_RE = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/;
+
+/** The text of the `## Use cases` section, up to the next top-level heading. */
+function useCasesSection(doc) {
+ const start = doc.indexOf('\n## Use cases\n');
+ if (start === -1) return null;
+ const rest = doc.slice(start + 1);
+ const end = rest.indexOf('\n## ', 3);
+ return end === -1 ? rest : rest.slice(0, end);
+}
+
+/**
+ * Parse the section into use cases:
+ * [{ prompt, blocks: [{ servers: [..], steps: [{ text, tools, resources, spends }] }] }]
+ */
+function parseUseCases(section) {
+ const cases = [];
+ for (const chunk of section.split(/\n### /).slice(1)) {
+ const heading = chunk.split('\n', 1)[0];
+ const prompt = heading.match(/\(`([a-z0-9-]+)`\)\s*$/)?.[1] ?? null;
+ const blocks = [];
+ let block = null;
+ for (const line of chunk.split('\n').slice(1)) {
+ const on = line.match(/^On ((?:`[a-z0-9-]+`(?:, | and )?)+)(?: \([^)]*\))?:$/);
+ if (on) {
+ block = { servers: [...on[1].matchAll(/`([a-z0-9-]+)`/g)].map((m) => m[1]), steps: [] };
+ blocks.push(block);
+ continue;
+ }
+ const step = line.match(/^\d+\. (.*)$/);
+ if (step && block) {
+ const ticks = [...step[1].matchAll(/`([^`]+)`/g)].map((m) => m[1]);
+ block.steps.push({
+ text: step[1],
+ tools: ticks.filter((t) => TOOL_RE.test(t)),
+ resources: ticks.filter((t) => t.startsWith('three://')),
+ spends: step[1].startsWith(SPEND_MARK),
+ });
+ }
+ }
+ cases.push({ heading, prompt, blocks });
+ }
+ return cases;
+}
+
+/** Sample arguments: every argument, or required ones only. */
+function sampleArgs(prompt, { optional }) {
+ const args = {};
+ for (const a of prompt.arguments) {
+ if (!a.required && !optional) continue;
+ args[a.name] = a.name === 'agentId' ? '{agentId}' : a.name === 'token' ? 'THREEsynthetic1111' : `sample ${a.name}`;
+ }
+ return args;
+}
+
+/** Every tool and resource a prompt can name on a server, across its argument shapes. */
+function renderedCalls(server, prompt) {
+ const catalog = SERVERS[server];
+ const tools = new Set();
+ const resources = new Set();
+ for (const optional of [true, false]) {
+ const out = renderPrompt(server, catalog, prompt.name, sampleArgs(prompt, { optional }));
+ out.tools.forEach((t) => tools.add(t));
+ out.resources.forEach((r) => resources.add(r));
+ }
+ return { tools, resources };
+}
+
+/**
+ * Check the parsed use cases against the live catalogs. Returns a list of
+ * human-readable problems; empty means the section matches the code.
+ */
+function auditUseCases(cases, servers = SERVERS) {
+ const problems = [];
+ const byPrompt = new Map(cases.map((c) => [c.prompt, c]));
+ for (const c of cases) {
+ if (!c.prompt) problems.push(`use case "${c.heading}" does not name its prompt as (\`name\`)`);
+ else if (!PROMPTS.some((p) => p.name === c.prompt)) problems.push(`use case names unknown prompt ${c.prompt}`);
+ }
+ for (const prompt of PROMPTS) {
+ const c = byPrompt.get(prompt.name);
+ if (!c) {
+ problems.push(`prompt ${prompt.name} has no use case`);
+ continue;
+ }
+ const offeredOn = Object.entries(servers)
+ .filter(([s, catalog]) => promptsFor(s, catalog).some((p) => p.name === prompt.name))
+ .map(([s]) => s);
+ const documentedOn = new Set(c.blocks.flatMap((b) => b.servers));
+ for (const s of offeredOn) {
+ if (!documentedOn.has(s)) problems.push(`${prompt.name}: offered on ${s} but no "On \`${s}\`:" block`);
+ }
+ for (const block of c.blocks) {
+ if (!block.steps.length) problems.push(`${prompt.name}: block for ${block.servers.join(', ')} has no steps`);
+ const named = new Set(block.steps.flatMap((st) => st.tools));
+ const namedResources = new Set(block.steps.flatMap((st) => st.resources));
+ for (const server of block.servers) {
+ const catalog = servers[server];
+ if (!catalog) {
+ problems.push(`${prompt.name}: unknown server ${server}`);
+ continue;
+ }
+ const byName = new Map(catalog.map((t) => [t.name, t]));
+ for (const tool of named) {
+ if (!byName.has(tool)) problems.push(`${prompt.name} on ${server}: names tool ${tool}, which ${server} does not publish`);
+ }
+ for (const uri of namedResources) {
+ if (!matchResource(server, uri)) problems.push(`${prompt.name} on ${server}: names resource ${uri}, which ${server} does not serve`);
+ }
+ if (!offeredOn.includes(server)) {
+ problems.push(`${prompt.name}: documented on ${server}, which does not offer it`);
+ continue;
+ }
+ const rendered = renderedCalls(server, prompt);
+ for (const tool of rendered.tools) {
+ if (!named.has(tool)) problems.push(`${prompt.name} on ${server}: the prompt calls ${tool}, which the use case does not name`);
+ }
+ for (const tool of named) {
+ if (!rendered.tools.has(tool)) problems.push(`${prompt.name} on ${server}: the use case names ${tool}, which the prompt never calls`);
+ }
+ for (const uri of rendered.resources) {
+ if (!namedResources.has(uri)) problems.push(`${prompt.name} on ${server}: the prompt reads ${uri}, which the use case does not name`);
+ }
+ for (const step of block.steps) {
+ for (const tool of step.tools) {
+ if (byName.get(tool)?.annotations?.destructiveHint === true && !step.spends) {
+ problems.push(`${prompt.name} on ${server}: step calling ${tool} moves funds but is not marked ${SPEND_MARK}`);
+ }
+ }
+ }
+ }
+ }
+ }
+ return problems;
+}
+
+const section = useCasesSection(DOC);
+
+describe('docs/mcp.md use cases', () => {
+ it('has a Use cases section', () => {
+ expect(section).toBeTruthy();
+ });
+
+ const cases = parseUseCases(section || '');
+
+ it('covers every guided prompt, in prompt-catalog order', () => {
+ expect(cases.map((c) => c.prompt)).toEqual(PROMPTS.map((p) => p.name));
+ });
+
+ it('names only live tools and resources, and exactly the ones each prompt calls', () => {
+ expect(auditUseCases(cases)).toEqual([]);
+ });
+
+ it('marks at least one spending step, and every spending step says what moves', () => {
+ const spends = cases.flatMap((c) => c.blocks.flatMap((b) => b.steps.filter((s) => s.spends)));
+ expect(spends.length).toBeGreaterThan(0);
+ for (const s of spends) expect(s.text.length).toBeGreaterThan(SPEND_MARK.length + 20);
+ });
+
+ it('fails when a tool the section names disappears from its server', () => {
+ // The drift this suite exists for: drop pay_and_call from mcp-agent and the
+ // audit must name it, not pass silently.
+ const without = { ...SERVERS, 'mcp-agent': agentCatalog.filter((t) => t.name !== 'pay_and_call') };
+ const problems = auditUseCases(cases, without);
+ expect(problems.some((p) => p.includes('pay_and_call'))).toBe(true);
+ });
+});