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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// three.ws Forge on OKX.AI: the A2MCP surface a buying agent calls to turn a
// prompt (or reference images) into a real, downloadable 3D model.
//
// This is the rebuilt marketplace listing (owner directive 2026-08-22). It
// gives an OKX.AI agent exactly what the "three.ws 3D Studio" custom GPT gives
// a ChatGPT user, over the marketplace's own payment rail instead of a free
// ChatGPT Action: describe a thing, get a GLB, a concept image, a browser
// viewer link, and a device-aware AR link that puts it in a real room.
//
// Why A2MCP and not plain REST: OKX lists a service as `serviceType: A2MCP`,
// and the 2026-07-04 rejection was "your A2MCP service has not been integrated
// with the OKX Agent Payments Protocol standard". A reviewer probing a listed
// endpoint speaks MCP Streamable HTTP JSON-RPC and expects an unpaid paid-tool
// call to answer a 402 whose accepts[] leads with eip155:196. So every listed
// row is a genuine MCP server, and the paid tool is genuinely x402-gated on the
// X Layer rail. api/okx/3d/[service].js owns the transport; this module owns
// the tools, the prices, and the discovery metadata.
//
// One surface per catalog row, built from the row itself:
//
// forge-draft / forge-standard / forge-hd forge_3d (paid) over a text prompt
// forge-image forge_3d (paid) over image links
// forge-status forge_status only, always free
//
// Every endpoint carries the free forge_status and getting_started tools too,
// so an agent polls the job where it paid for it and never has to discover a
// second host mid-flight.
//
// It is a front, not a pipeline: generation runs through the same
// gpt-forge-client → /api/gpt-forge lane the GPT uses, and the response is
// shaped by the same api/_mcp-studio/studio-shape.js. The marketplace and the
// GPT cannot drift into two different contracts over one generator.
import Ajv from 'ajv';
import addFormats from 'ajv-formats';
import { makeDispatcher, PROTOCOL_VERSION } from '../_lib/mcp-dispatch.js';
import { buildGettingStartedTool, GETTING_STARTED_TOOL } from '../_lib/mcp-getting-started.js';
import { buildBazaarSchema } from '../_lib/x402-spec.js';
import { withService } from '../_lib/x402/bazaar-helpers.js';
import { X402_HEADER_ERROR } from '../_lib/x402-xlayer-okx.js';
import { catalogEntry, FORGE_TOOL, FORGE_STATUS_TOOL } from '../_lib/okx-catalog.js';
import { startForge, pollOnce, originFromReq } from '../_mcp-studio/gpt-forge-client.js';
import { shapeSubmit, shapePoll, tierOf } from '../_mcp-studio/studio-shape.js';
import { checkPromptSafety } from '../_mcp-studio/safety.js';
import { objectStorageUsable } from '../_lib/r2.js';
import { renderTurntable, describeGeometry, fetchGeometryStats } from '../_lib/3d-vision.js';
export { PROTOCOL_VERSION, FORGE_TOOL, FORGE_STATUS_TOOL };
const BASE = 'https://three.ws';
const STATUS_ENDPOINT = `${BASE}/api/okx/3d/forge-status`;
// Free on every endpoint: the buyer can see what it bought.
const LOOK_TOOL = 'look_at_model';
const DOCS_URL = `${BASE}/docs/okx-marketplace`;
// Every listed forge row. A row not in this set is not servable here.
export const FORGE_SERVICE_IDS = Object.freeze([
'forge-draft',
'forge-standard',
'forge-hd',
'forge-image',
'forge-status',
]);
export function isForgeService(id) {
return FORGE_SERVICE_IDS.includes(id);
}
function toolError(code, message, extra = {}) {
return {
isError: true,
content: [{ type: 'text', text: `${code}: ${message}` }],
structuredContent: { ok: false, error: code, message, ...extra },
};
}
function toolOk(text, structured) {
return { content: [{ type: 'text', text }], structuredContent: structured };
}
// Lane failures already carry a designed code + caller-facing message from
// gpt-forge-client. Map them to an MCP tool error the buyer can act on rather
// than letting a generic throw become a -32603 with no recovery advice.
function laneError(err) {
switch (err?.code) {
case 'not_configured':
return toolError('unavailable', '3D generation is temporarily unavailable, try again later.');
case 'busy':
return toolError('busy', err.message || 'The generator is saturated, try again shortly.', {
retry_after: err.retryAfter || 10,
});
case 'timeout':
return toolError('timeout', err.message || 'The generator took too long to accept the job, try again.', {
retry_after: 10,
});
case 'unknown_job':
return toolError('unknown_job', err.message || 'That job id is not recognized.');
case 'tier_unavailable':
// The paid HD row refuses rather than quietly serving a lower tier.
// This error answers BEFORE settlement, so the buyer is not charged.
return toolError('tier_unavailable', err.message, { retry_after: err.retryAfter || 60, charged: false });
default:
return toolError('generation_failed', err?.message || 'The generator could not start this job.');
}
}
// A pending job is polled at the free forge-status endpoint, so `poll` is a
// real URL an agent can hit, and `poll_tool` names the JSON-RPC tool to call
// there. Both, because buyers in this marketplace read either.
// `paid: true` is what makes a failed-job message honest on this surface: these
// rows settle when the lane accepts the job, so the free lanes' "it costs
// nothing to try again" would be a lie told to a buyer who was already charged.
const POLL_OPTS = { pollPath: STATUS_ENDPOINT, paid: true };
// Every finished creation has a public page at /m/<creation id>: the model
// spinning in a viewer, AR and fullscreen, download, embed and share, comments
// and likes. It is the one link an agent can hand a human that does everything.
// The forge lane records the creation id on submit and on every poll frame, so
// the page link is available the moment the job is done.
const CREATION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
function pageUrlOf(base, data) {
const id = data?.creation_id;
return typeof id === 'string' && CREATION_ID_RE.test(id) ? `${base}/m/${id}` : null;
}
function withPollTool(shaped, { base, data, title }) {
if (shaped.status === 'pending') {
return {
...shaped,
poll_tool: FORGE_STATUS_TOOL,
poll_endpoint: STATUS_ENDPOINT,
// Copy these verbatim into the next forge_status call.
poll_arguments: { job_id: shaped.job, ...(title ? { title } : {}) },
};
}
if (shaped.status === 'done') {
const pageUrl = pageUrlOf(base, data);
return pageUrl ? { ...shaped, pageUrl } : shaped;
}
return shaped;
}
// The text content is what most buying agents relay to their human verbatim,
// so it carries every link, not just the file. An agent that never reads
// structuredContent still hands over the viewer, the AR launch and the page.
function summarize(shaped) {
if (shaped.status === 'done') {
return [
'Model ready.',
`Download (GLB): ${shaped.glbUrl}`,
`View in browser: ${shaped.viewerUrl}`,
`See it in your room (AR): ${shaped.arUrl}`,
...(shaped.pageUrl ? [`Model page (share, embed, download): ${shaped.pageUrl}`] : []),
...(shaped.previewImageUrl ? [`Concept image: ${shaped.previewImageUrl}`] : []),
].join('\n');
}
if (shaped.status === 'error') return shaped.error;
const eta = shaped.etaSeconds ? ` ETA ~${shaped.etaSeconds}s.` : '';
const preview = shaped.previewImageUrl ? ` Concept image so far: ${shaped.previewImageUrl}` : '';
return `Job accepted.${eta} Poll ${FORGE_STATUS_TOOL} with job_id "${shaped.job}" every 5s until status is "done".${preview}`;
}
function buildForgeTool(entry) {
const isImageLane = entry.lane?.mode === 'image_to_3d';
const priceLine = `$${entry.priceUsd} per call, charged only when the job is accepted.`;
return {
name: FORGE_TOOL,
title: `Forge a 3D model (paid, $${entry.priceUsd})`,
description:
`${priceLine} ${entry.describes.capability} ` +
`Async: returns a job id immediately, then poll ${FORGE_STATUS_TOOL} (free) every few ` +
'seconds until status is "done". You receive the GLB file, a browser viewer link, an ' +
'augmented-reality link that places the model in a real room, a shareable model page, and ' +
'the concept image. Invalid input fails before settlement, so a rejected call costs nothing.',
annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true },
inputSchema: entry.inputSchema,
async handler(args, _auth, req) {
const base = originFromReq(req);
const prompt = typeof args.prompt === 'string' ? args.prompt.trim() : '';
// Age-13+ content gate BEFORE any GPU work or settlement. The same
// gate the GPT Store surface runs; a refused prompt never settles.
if (prompt) {
const safety = checkPromptSafety(prompt);
if (!safety.allowed) return toolError('prompt_rejected', safety.message);
}
if (!isImageLane && !prompt) {
return toolError('invalid_input', 'prompt is required: describe one subject in 3 to 1000 characters.');
}
// Delivery, not just generation, has to be up before we take money.
// This row settles when the lane ACCEPTS the job, and the finished mesh
// reaches the buyer only once materializeCreation has copied it into the
// delivery bucket. On 2026-09-09 that copy was failing on a rejected R2
// credential for every job since 2026-09-07, so the lane still accepted
// (and charged) work that could never reach a `done` state: a buyer paid
// and polled forever. The probe is the cached, single-flighted one the
// browser-upload path already relies on, so this costs a paid call one
// signed list per minute, and it fails OPEN on a transient fault: only a
// deterministically rejected or unconfigured credential refuses here.
const storage = await objectStorageUsable();
if (!storage.ok) {
return toolError('delivery_unavailable', 'model delivery storage is unavailable right now, so this call was not charged; try again shortly', {
retry_after: 120,
charged: false,
});
}
// The high tier is hold-gated on the generator; the buyer has already
// paid this row's price, so the job runs operator-funded (internal seed),
// the same way the custom GPT runs it. strictTier keeps the promise: if
// the HD lane will not take the job, refuse before settlement instead of
// charging HD money for a standard mesh.
const high = entry.lane?.tier === 'high';
let job;
try {
job = await startForge(base, {
prompt: prompt || undefined,
imageUrls: isImageLane ? args.image_urls : undefined,
aspect: isImageLane ? '1:1' : args.aspect_ratio,
...(entry.lane?.tier ? { tier: entry.lane.tier } : {}),
...(entry.lane?.path ? { path: entry.lane.path } : {}),
...(high ? { internal: true, strictTier: true } : {}),
});
} catch (err) {
return laneError(err);
}
// Belt and braces: a lane that answered with a tier it was not asked
// for is refused the same way, still before settlement.
if (high && tierOf(job) && tierOf(job) !== 'high') {
return toolError('tier_unavailable', 'the high-detail lane is not available right now; try again shortly', {
retry_after: 60,
charged: false,
});
}
const shaped = withPollTool(shapeSubmit(job, base, prompt, POLL_OPTS), { base, data: job, title: prompt });
return toolOk(summarize(shaped), { ok: true, service: entry.id, ...shaped });
},
};
}
function buildStatusTool() {
const entry = catalogEntry('forge-status');
return {
name: FORGE_STATUS_TOOL,
title: 'Check a forge job (free)',
description:
'FREE. Reports the live state of a three.ws forge job and returns the finished GLB, the ' +
'concept image, a browser viewer link, an augmented-reality link and a shareable model ' +
'page once it is done. Poll every 5 seconds. No payment, account, or key required.',
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
inputSchema: entry.inputSchema,
async handler(args, _auth, req) {
const base = originFromReq(req);
const jobId = String(args.job_id || '').trim();
let data;
try {
data = await pollOnce(base, jobId);
} catch (err) {
return laneError(err);
}
// The poll frame carries the job's own prompt, so the viewer and AR
// pages get a title even when the buyer never passed one.
const title =
typeof args.title === 'string' && args.title.trim()
? args.title
: typeof data?.prompt === 'string'
? data.prompt
: '';
const shaped = withPollTool(shapePoll(data, base, jobId, title, POLL_OPTS), { base, data, title });
const body = { ok: shaped.status !== 'error', ...shaped };
return shaped.status === 'error'
? { isError: true, content: [{ type: 'text', text: shaped.error }], structuredContent: body }
: toolOk(summarize(shaped), body);
},
};
}
// Endpoint-level v2 bazaar discovery entry, in the shape agentic.market's
// validator expects. Describes a JSON-RPC 2.0 tools/call against THIS server's
// tools and the job handle that comes back. Without it the 402 envelope
// inherits the default that describes a different server's tools, and an agent
// that followed it would pay and then send a call this dispatcher rejects.
function forgeBazaarExtension(entry, paidTool) {
// The image example must point at an image that actually loads: this one is
// the single runnable example on the image row, and a buyer that follows it
// pays before finding out. It read /og/three-ws.png, which 404s.
const exampleArguments = paidTool
? entry.lane?.mode === 'image_to_3d'
? { image_urls: [`${BASE}/logo.png`] }
: { prompt: 'a low-poly orange fox sitting down' }
: { job_id: 'f1.abc123' };
const exampleBody = {
jsonrpc: '2.0',
id: 1,
method: 'tools/call',
params: { name: paidTool ? FORGE_TOOL : FORGE_STATUS_TOOL, arguments: exampleArguments },
};
const exampleResponse = {
jsonrpc: '2.0',
id: 1,
result: {
content: [{ type: 'text', text: `Job accepted. Call ${FORGE_STATUS_TOOL} with job_id f1.abc123 until status is "done".` }],
structuredContent: {
ok: true,
status: 'pending',
job: 'f1.abc123',
poll_tool: FORGE_STATUS_TOOL,
poll_endpoint: STATUS_ENDPOINT,
format: 'glb',
etaSeconds: 45,
},
},
};
const toolLine = paidTool
? `Tool names: ${FORGE_TOOL} (paid, $${entry.priceUsd}), ${FORGE_STATUS_TOOL} (free job polling), ${GETTING_STARTED_TOOL} (free overview).`
: `Tool names: ${FORGE_STATUS_TOOL} (free job polling), ${GETTING_STARTED_TOOL} (free overview).`;
const requestBodySchema = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
required: ['jsonrpc', 'method'],
properties: {
jsonrpc: { type: 'string', const: '2.0' },
id: { type: ['string', 'number'] },
method: {
type: 'string',
enum: ['initialize', 'tools/list', 'tools/call', 'ping'],
description: 'MCP JSON-RPC method.',
},
params: {
type: 'object',
description: `For tools/call: { name, arguments }. ${toolLine} See tools/list.`,
},
},
};
const responseBodySchema = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
properties: {
jsonrpc: { type: 'string', const: '2.0' },
id: { type: ['string', 'number'] },
result: {
type: 'object',
properties: {
content: {
type: 'array',
items: {
type: 'object',
required: ['type', 'text'],
properties: { type: { type: 'string', enum: ['text'] }, text: { type: 'string' } },
},
},
},
},
error: { type: 'object', properties: { code: { type: 'number' }, message: { type: 'string' } } },
},
};
return {
discoverable: true,
info: {
input: { type: 'http', method: 'POST', body: exampleBody, bodyType: 'json' },
output: { type: 'json', example: exampleResponse },
},
schema: buildBazaarSchema({
method: 'POST',
bodyType: 'json',
bodySchema: requestBodySchema,
outputSchema: responseBodySchema,
}),
};
}
const ajv = new Ajv({ allErrors: false, strict: false });
addFormats(ajv);
// look_at_model: free on every forge endpoint.
//
// A buyer who pays for a model and receives a URL is in exactly the bind this
// whole marketplace was built to solve: it cannot open the file it just bought.
// MCP image content blocks can carry the render, so the buying agent LOOKS at
// its purchase, confirms it got what it paid for, and can ask for a different
// prompt if it did not. No other seller on this marketplace can hand an agent
// a picture of the goods.
function buildLookTool() {
return {
name: LOOK_TOOL,
title: 'Look at a 3D model (free)',
description:
'FREE. See a model instead of just holding a link to it. Renders the GLB from several angles and ' +
'returns the frames as images you can actually look at, plus its geometry and a plain reading of ' +
'what the numbers mean. Use it on anything this service returned to confirm you got what you paid ' +
'for, or on any other public https .glb.',
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
inputSchema: {
type: 'object',
required: ['glb_url'],
additionalProperties: false,
properties: {
glb_url: { type: 'string', minLength: 12, maxLength: 2048 },
views: {
type: 'array',
maxItems: 6,
items: { type: 'string', enum: ['front', 'three-quarter', 'side', 'back', 'top', 'bottom'] },
},
size: { type: 'integer', minimum: 128, maximum: 1024 },
},
},
async handler(args) {
const glbUrl = String(args?.glb_url || '').trim();
if (!/^https:\/\//i.test(glbUrl)) {
return toolError('invalid_url', 'glb_url must be a public https URL to a .glb file.');
}
let turntable;
try {
turntable = await renderTurntable({ glbUrl, views: args?.views, size: args?.size ?? 512 });
} catch (err) {
return toolError('render_failed', String(err?.message || 'could not render this model').slice(0, 300));
}
const stats = await fetchGeometryStats(BASE, glbUrl);
const notes = describeGeometry(stats);
const shown = turntable.frames.map((f) => f.view).join(', ');
const content = [
{
type: 'text',
text:
`Rendered from ${turntable.frames.length} angle(s): ${shown}. ` +
(notes.length ? `Geometry: ${notes.join(' ')} ` : '') +
'Look at the frames below: is the subject complete and recognisable, is the far side ' +
'finished, is anything melted or fused?',
},
];
for (const frame of turntable.frames) {
content.push({ type: 'text', text: `View: ${frame.view}` });
content.push({ type: 'image', data: frame.png.toString('base64'), mimeType: 'image/png' });
}
return {
content,
structuredContent: {
ok: true,
model_url: glbUrl,
size: turntable.size,
views: turntable.frames.map((f) => ({ view: f.view, theta: f.theta, phi: f.phi })),
...(turntable.failed.length ? { missing_views: turntable.failed } : {}),
...(stats ? { stats, notes } : {}),
},
};
},
};
}
function buildSurface(id) {
const entry = catalogEntry(id);
if (!entry) throw new Error(`okx forge: no catalog entry "${id}"`);
const paid = entry.priceUsd !== '0';
const paidTool = paid ? buildForgeTool(entry) : null;
const statusTool = buildStatusTool();
const lookTool = buildLookTool();
const gettingStarted = buildGettingStartedTool({
server: `three.ws Forge, ${entry.name}`,
tagline:
'Text or images to a real, downloadable 3D model (GLB), with a browser preview and an ' +
'augmented-reality link that places it in a real room.',
tools: [paidTool, statusTool, lookTool].filter(Boolean),
priceFor: (name) => (paid && name === FORGE_TOOL ? { amount_usdc: Number(entry.priceUsd) } : null),
access: paid
? [
`Pay per call with x402 on X Layer (chain 196): $${entry.priceUsd} per ${FORGE_TOOL} call.`,
`${FORGE_STATUS_TOOL} and this tool are free: no payment, account, or key.`,
'Full service index (free): https://three.ws/api/okx/3d/catalog',
]
: [
'Free: no payment, account, or key. Poll any three.ws forge job here.',
'Full service index (free): https://three.ws/api/okx/3d/catalog',
],
links: {
docs: DOCS_URL,
catalog: `${BASE}/api/okx/3d/catalog`,
health: `${BASE}/api/okx/3d/health`,
try_it_in_a_browser: `${BASE}/forge`,
example_model_page: `${BASE}/creations`,
},
});
const toolDefs = [gettingStarted, ...(paidTool ? [paidTool] : []), statusTool, lookTool];
const TOOL_CATALOG = toolDefs.map(({ handler, scope, ...pub }) => pub);
const TOOLS = Object.fromEntries(
toolDefs.map((d) => [
d.name,
{ scope: d.scope, handler: d.handler, validate: d.inputSchema ? ajv.compile(d.inputSchema) : null },
]),
);
const description = paid
? `three.ws Forge, ${entry.name}: A2MCP service that turns ${entry.lane?.mode === 'image_to_3d' ? 'reference images' : 'a text description'} ` +
`into a downloadable 3D model (GLB) with a browser viewer and an augmented-reality link. ` +
`$${entry.priceUsd} per call on X Layer via x402; job polling is free. Operated by three.ws.`
: 'three.ws Forge job status: free A2MCP service that reports the live state of any three.ws ' +
'forge job and returns the finished model, viewer and augmented-reality links. Operated by three.ws.';
const challenge = {
description,
// The 402 body's `error` names the header the buyer must send back. The
// platform-wide default names `X-PAYMENT`, which is x402 **v1**; OKX
// buyers speak v2 and send `PAYMENT-SIGNATURE` (their SDK reads only
// that name). Leaving the v1 default here told a reviewer of an
// x402-v2 listing, in the one string they are guaranteed to read, that
// we implement the version we do not. Both names are accepted on the
// wire, so the message names both, v2 first.
error: X402_HEADER_ERROR,
bazaar: forgeBazaarExtension(entry, paidTool),
...withService({
serviceName: `three.ws Forge, ${entry.name}`,
tags: ['x402', 'mcp', '3d', 'forge', 'okx'],
}),
};
return {
entry,
challenge,
TOOL_CATALOG,
TOOLS,
// Free tools servable to the anonymous principal with no OAuth/x402:
// discovery plus status polling. The paid tool is deliberately not here.
isPublicTool: (name) => name === GETTING_STARTED_TOOL || name === FORGE_STATUS_TOOL || name === LOOK_TOOL,
// x402 price (atomic USDC string) for one tools/call, or null when free.
x402Amount: (toolName) => (paid && toolName === FORGE_TOOL ? entry.amountAtomics : null),
dispatch: makeDispatcher({
serverInfo: { name: `three-ws-forge-${id}`, version: '1.0.0' },
instructions: paid
? `Call ${FORGE_TOOL} (paid, $${entry.priceUsd}) with your description, then poll ` +
`${FORGE_STATUS_TOOL} (free) with the returned job_id until status is "done". Call ` +
`${GETTING_STARTED_TOOL} (free) for the full overview.`
: `Call ${FORGE_STATUS_TOOL} (free) with a job_id from any three.ws forge service until ` +
`status is "done". Call ${GETTING_STARTED_TOOL} (free) for the full overview.`,
catalog: TOOL_CATALOG,
tools: TOOLS,
logName: `mcp-okx-${id}`,
}),
};
}
// One surface per listed row, built on first use and reused after: the
// dispatcher and its compiled validators are per-endpoint immutable state.
const surfaces = new Map();
export function forgeSurface(id) {
if (!isForgeService(id)) return null;
if (!surfaces.has(id)) surfaces.set(id, buildSurface(id));
return surfaces.get(id);
}