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.
three.ws 3D Studio — MCP server
Turn text or an image into an interactive, animation-ready 3D model — and rig,
animate, pose, edit, retexture, and analyze it — directly from Claude, Cursor,
watsonx Orchestrate, or any MCP client. A focused companion to the main three.ws
MCP server, registered separately as io.github.nirholas/threews-3d-studio.
- Endpoint:
https://three.ws/api/mcp-3d - Transport: Streamable HTTP (MCP
2025-06-18, JSON-RPC 2.0) - Auth: OAuth 2.1 (same three.ws authorization server as
/api/mcp) or x402. The server is its own OAuth resource,https://three.ws/api/mcp-3d, described athttps://three.ws/.well-known/oauth-protected-resource/api/mcp-3d, so stock MCP SDK connectors can sign in; tokens minted for/api/mcpare accepted here too - Backends: image→3D on the self-hosted GCP reconstruction worker when configured, else Microsoft TRELLIS on Replicate; text→image on the free lanes first (FLUX on NVIDIA NIM, Vertex AI Imagen) with Replicate FLUX as the paid backstop; Meshy / Tripo / Rodin / Stability native geometry (BYOK); Make-It-Animatable auto-rig (self-hosted GPU worker); IBM Granite (watsonx.ai) for prompt direction + material generation
The pipeline
The tools compose into one flow — each step's output feeds the next:
direct_prompt ─▶ text_to_3d ─┐
image_to_3d ─┴▶ generation_status ─▶ auto_rig_model ─▶ apply_animation
└─▶ pose_model
mesh ops: remesh_model · stylize_model · segment_model · retexture_model · retexture_region · generate_material
analyze: inspect_model · optimize_model preview: preview_3d
"Optimize this idea, generate it, rig it, and make it wave." →
direct_prompt→text_to_3d→ pollgeneration_status→auto_rig_model→ poll →apply_animation(animation: "wave").
Tools
Generate
| Tool | What it does |
|---|---|
text_to_3d(prompt, aspect_ratio?, tier?, path?, backend?) |
Text → reference image → reconstructed GLB. Returns a job_id + the intermediate preview image. |
image_to_3d(image_url | image_urls[], prompt?, tier?, path?, backend?) |
Reconstruct a GLB from 1–4 reference views (multi-view removes back-of-object hallucination). Returns a job_id. |
generation_status(job_id) |
Poll any job. When done, returns the GLB URL and an inline <model-viewer> artifact. Provider-aware: routes geometry/self-host jobs to the right upstream. |
cad_generate(prompt, parent_id?, values?) |
Description → parametric CAD: a build123d program the OpenCascade kernel has accepted, saved with STEP, STL, GLB (true scale) and an SVG drawing, plus a /cad/:id page with dimension sliders. Synchronous, usually 20-90 s. For brackets, enclosures, gears and other functional parts. See CAD Forge. |
cad_rebuild(id, values) |
Rebuild a CAD Forge design at new parameter values (e.g. {"WIDTH": 120}) on the kernel, no model involved. Exact and cached per value set. |
Rig, animate & pose
| Tool | What it does |
|---|---|
auto_rig_model(glb_url) |
Add a Mixamo-named humanoid skeleton, per-vertex skin weights, and ARKit expression blendshapes to a static GLB (Make-It-Animatable). Returns a job_id; poll for the rigged GLB. |
list_animations(category?) |
The curated, retargetable animation-clip catalogue (names, categories, loop flags). |
animation_signature(clip, slot?) |
A clip's measured motion: energy, tempo, leading region, loop seam, travel. Pass slot for an ok/warn fit verdict against a runtime slot. |
find_similar_animations(clip, limit?) |
The library ranked by measured-motion distance from a reference clip: "more like this" for animations. |
apply_animation(model_url, animation, format?, speed?) |
Retarget a preset clip onto a rigged GLB — returns the retargeted AnimationClip JSON (or a baked animated GLB). |
text_to_animation(prompt, model_url?, duration_seconds?, format?, speed?) |
Generate a brand-new motion from a prompt ("waving confidently", "a slow tai-chi sweep") with a motion-diffusion model, then retarget it onto a rigged humanoid GLB with the same engine apply_animation uses. |
pose_model(prompt) |
Map a pose description to a deterministic seed + full Euler joint-rotation map from the in-repo preset library. Deterministic: the same prompt always returns the same seed. Priced at $0.01 (see the table below). |
Edit & process the mesh
| Tool | What it does |
|---|---|
remesh_model(mesh_url, operation?, target_faces?, output_format?) |
Repair, simplify (quadric decimation), or convert format (incl. FBX with skeleton for Unity/Unreal). Reads GLB/GLTF/OBJ/STL/PLY/OFF/DAE and binary FBX 7.1+. |
stylize_model(mesh_url, style?, resolution?, output_format?) |
One-pass geometric restyle: voxel, brick (LEGO-like), voronoi lattice, lowpoly. Reads GLB/GLTF/OBJ/STL/PLY/OFF/DAE; convert an FBX with remesh_model first. |
segment_model(mesh_url, method?, max_parts?, …) |
Split into named, separable parts (each a node) + a parts manifest. Reads GLB/GLTF/OBJ/STL/PLY/OFF/DAE; convert an FBX with remesh_model first. |
retexture_model(mesh_url, prompt, num_views?, texture_size?) |
Paint a fresh texture from a prompt (SDXL + ControlNet depth, multi-view back-projection). |
retexture_region(mesh_url, mask_url, prompt?, color?, …) |
Magic-brush: repaint only a masked UV region, feathering the seam. |
generate_material(description, name?) |
IBM Granite → a glTF 2.0 PBR material (base color, metallic, roughness, emissive). |
remove_background(image_url, model?) |
Strip the background from a photo or illustration, returning a transparent PNG: a clean input for image_to_3d. |
Assist, analyze & preview
| Tool | What it does |
|---|---|
direct_prompt(idea, style?) |
IBM Granite rewrites a vague/multi-subject idea into one optimized single-subject text_to_3d prompt + structured directives. |
inspect_model(url) |
Structural stats: meshes, triangles, materials, textures, animations, extensions. |
optimize_model(url) |
Actionable size/perf suggestions: Draco/Meshopt, KTX2, triangle budget. |
preview_3d(glb_url, …) |
Render any public GLB as an interactive <model-viewer> artifact (orbit, AR, auto-rotate). |
export_ar(glb_url, title?, kind?) |
Read-only: turn any public GLB into the device-aware AR link set (arLaunchUrl, sceneViewerUrl, viewerUrl, plus irlUrl when kind: "avatar") and a Spatial MCP artifact. Free. See AR & WebXR. |
getting_started(section?) |
Free, no credentials: an overview of every tool, how to get access, and the useful links. Call it first to orient. |
save_avatar(glb_url, name, visibility?, source_prompt?, tags?) |
Copy a generated GLB into three.ws storage (so it survives the provider URL expiring) and register it as a named avatar you own. Free. |
capture_scene(video_url, mode?, fps?, …) |
Reconstruct a real space from a video walkaround into an explorable 3D point cloud (LingBot-Map streaming reconstructor, drift-corrected across the clip). |
grade_sim_readiness(glb_url, hash?) |
Free: can this GLB be dropped into a physics simulator (MuJoCo, Isaac, Bullet, a game engine) and behave? Returns simulation_ready, needs_scale, needs_repair, or unusable, plus the measurements behind the verdict. |
anchor_provenance(glb_url, creator?, prompt?, …) |
Issue a signed content credential for a generated GLB and anchor its hash on Solana, so anyone can later check authenticity for free. |
verify_provenance(glb_url, hash?) |
Free: recompute the model’s content hash, check the signed credential and its on-chain anchor, and answer verified, tampered, or unknown. |
read_resource(uri?, format?) |
Free: read a live three:// resource (three://me, three://agents, three://agents/<id>, three://models, three://assets/<id>) for clients that render tools but not MCP resources. Omit uri to list what you can read. |
validate_spatial_response(artifact) |
Free: check a structured-content payload against the open Spatial MCP artifact shape before you ship it. |
x402_preflight(origin, network?) |
Read-only, free: fetch an x402 seller's signed payability attestation from <origin>/.well-known/x402-preflight, verify its ed25519 signature, expiry, and subject, and answer whether that seller can actually settle before you pay it. An attestation that does not verify is reported as unverified, never as health. Spec: specs/x402-preflight.md. |
Generation, rigging, and most mesh ops are asynchronous: the tool returns a
job_id immediately, then you poll generation_status (reconstruction is
typically 30–90s; rigging 30–90s; texture jobs 2–5 min). When a job finishes,
generation_status returns a text/html resource — display it as an inline 3D
artifact.
Embodied on-chain identity
Every persona minted with create_agent_persona (see the
free studio's embodiment tools
— the persona lifecycle is shared, only the identity layer below is paid-track)
carries a real, deterministic Solana wallet: the avatar IS the wallet. The
same persona_id always re-derives the same address — no private key is ever
stored anywhere, and none is ever returned in a tool response or written to a
log (see api/_lib/persona-wallet.js for the
derivation scheme).
| Tool | What it does |
|---|---|
persona_identity(persona_id, network?) |
Read-only: wallet address, live SOL/USDC balance, ERC-8004-style reputation, token holdings, a resolved SNS nameplate, and the visual tiers below. |
persona_payment_preview(persona_id, to, usdc, session_id?, network?) |
Read-only: the paying wallet and its live USDC balance, the recipient, the balance afterwards, session spend against the cap, and every rule that would refuse the transfer (would_execute plus blockers). Moves nothing; show it, get a yes, then call persona_tip or persona_send. |
persona_tip(persona_id, to, usdc, session_id?, memo?, network?, confirm?) |
Send a small USDC tip from the persona's own wallet. Real, irreversible on-chain settlement. |
persona_send(persona_id, to, usdc, session_id?, memo?, network?, confirm?) |
The general-purpose USDC send from the persona's own wallet. Same guardrails as persona_tip. |
Guardrails (env-tunable — PERSONA_MAX_TIP_USDC, PERSONA_MAX_SESSION_USDC, PERSONA_CONFIRM_ABOVE_USDC):
- Per-call cap — $1 USDC by default. An amount over the cap is rejected
with
over_call_capbefore any signature is built. - Per-session cap — $5 USDC cumulative by default, tracked durably
(Postgres in production, a local JSON ledger in dev) against the caller's
session_id(or a persona+UTC-day bucket when omitted). - Confirmation threshold — $0.25 USDC by default. Above it, the call must
carry
confirm: trueor it returnsconfirmation_required. - Owner only. A persona created by a signed-in three.ws account moves funds
only for that account: any other caller gets
not_owner, because thepersona_idtravels in every shared embodiment URL. A persona minted with no account keeps thepersona_id-as-capability model it was created under.
Settlement rides the same MEV-aware execution engine every other outbound transfer on the platform uses — no mocked transfer, ever. USDC is the only settlement asset; any other mint is out of scope for these tools.
Visual binding. persona_identity's response (and the live
GET /api/mcp3d/persona-identity?id=… feed the embodiment embed polls when
opened with ?wallet=1) includes a visual block —
reputation_tier, holdings_tier, muted, verified_name — that the shared
EmbodimentStage (apps-sdk/embodiment/chain-visuals.js) maps onto the body:
an aura ring colored + intensity-scaled by reputation tier, a cosmetic badge
for the holdings tier, a dimmed "muted" look under a low/zero balance, and a
nameplate for a verified .sol name. Every tier — including unranked / none /
unmuted — has a designed mapping, so a fresh, unfunded persona still renders a
real (not blank) identity.
Identity card. persona_identity also returns an identity_card block
(api/_lib/persona-identity-card.js) — a pure, verifiable projection of the
same data, in the same spirit as agent_hire's provenance block
(mcp-server/src/lib/agent-commerce.js#buildProvenance): wallet, balance,
reputation tier, holdings tier, verified name, muted flag, and a fetch
timestamp.
Quality tiers & generation paths
text_to_3d / image_to_3d take three optional axes (see
api/_lib/forge-tiers.js):
tier:draft(12k poly, fast),30k, default),standard(high(~200k + PBR, slower). Honoured by poly-aware engines; on the default image engine it's recorded as provenance.path:image(reference-image reconstruction, the platform-keyed default) orgeometry(native text/image→mesh, cleaner topology, BYOK).backend: a three.ws engine name;auto(the default) picks the best engine for the path. Responses report the engine under the same branded name. Legacy vendor ids are still accepted as hidden aliases, and an engine that does not serve the chosen path is ignored.
| Engine | Runs on | Path(s) | Key | Notes |
|---|---|---|---|---|
three-image |
platform | image | platform | The default. No poly target. |
three-geometry |
Meshy | geometry, image | BYOK | Native text→geometry, quad topology. |
three-geometry-pro |
Tripo | geometry, image | BYOK | Cleanest quad topology. |
three-sculpt |
Rodin | geometry, image | BYOK | High-poly detail. |
three-instant |
Stability | image | BYOK | Fast single-image. |
three-detail |
platform | image | platform | Poly-aware; reconstructs on the platform lane. |
The image path on this server always reconstructs on the platform provider: the
self-hosted GCP reconstruction worker when GCP_RECONSTRUCTION_KEY and
GCP_RECONSTRUCTION_URL are set, otherwise TRELLIS on Replicate. The free-lane
walk of /api/forge (self-host TRELLIS and Hunyuan3D, the HuggingFace Spaces
lane, NVIDIA NIM, with failover between them) is not wired into this server, so
the HuggingFace engine is deliberately not selectable here. Free text→3D over
MCP is the forge_free tool on the free 3D Studio
(/api/mcp-studio).
BYOK note: the geometry backends (Meshy/Tripo) have no platform key. Supply
your own via the x-forge-provider-key request header (or a key stored on your
three.ws account). Without one, the geometry path returns a designed needs_key
result and the image path still works keyless. The job handle for a geometry
job is an opaque forge token; generation_status decodes it and re-resolves the
key per poll.
Access & pricing
Discovery is free: a discovery-only batch (initialize, tools/list, ping)
and the public getting_started tool answer with no credentials, so any x402
agent, registry validator, or crawler can read the catalog before deciding to
pay.
curl -s https://three.ws/api/mcp-3d \
-H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
One deliberate exception: an MCP protocol client still gets 401 on
discovery. A request carrying mcp-protocol-version, mcp-session-id, or an
Accept of text/event-stream (the MCP TS SDK, the Inspector, the claude.ai
connector) is answered with a WWW-Authenticate challenge instead, because the
MCP authorization spec (RFC 9728) requires a 401 for the client to find the
protected-resource metadata and start the OAuth flow. That branch is
isMcpProtocolClient in api/_mcp/auth.js. So adding the
connector and signing in works; a plain curl that sets the SSE accept header
sees a challenge rather than the catalog, and should drop that header to browse.
For tool calls there are two lanes:
- OAuth (three.ws account) — operator-funded. Sign in once and every studio tool runs at no per-call charge, bounded by rate limits.
- x402 (pay per call, no account) — send a USDC payment (Base or Solana
mainnet) with the request. The 402 challenge quotes the exact price of the
tools you're calling; batches are priced as the sum of their calls. Same
numbers as
POST /api/x402/forge, single source:api/_mcp3d/pricing.js.
| Tool | Price (USDC) |
|---|---|
text_to_3d / image_to_3d |
by tier — $0.05 draft / $0.15 standard / $0.50 high |
auto_rig_model, retexture_model, retexture_region |
$0.05 |
stylize_model, remesh_model, segment_model |
$0.02 |
capture_scene, anchor_provenance |
$0.05 |
cad_generate |
$0.05 |
cad_rebuild |
$0.01 |
remove_background, pose_model, apply_animation, direct_prompt, generate_material |
$0.01 |
generation_status, preview_3d, list_animations, animation_signature, find_similar_animations, text_to_animation, inspect_model, optimize_model, save_avatar, export_ar, verify_provenance, grade_sim_readiness, x402_preflight, the persona tools (including persona_payment_preview), read_resource, validate_spatial_response, getting_started |
free |
Payment settles only after the work succeeds — a wholesale failure costs nothing, and the same signed payment cannot be replayed.
IBM Granite tools
direct_prompt and generate_material call IBM Granite foundation models via
watsonx.ai. They're operator-funded: set WATSONX_API_KEY and
WATSONX_PROJECT_ID on the server and end users pay nothing extra for them — no
IBM Cloud account required on the caller side. If watsonx isn't configured, both
return a clear "not configured" error rather than failing mid-call.
Use on claude.ai / watsonx Orchestrate
Add the connector with URL https://three.ws/api/mcp-3d and complete the OAuth
flow (or connect it from the watsonx Orchestrate MCP catalog). Then:
"Make a 3D model of a low-poly red fox sitting upright, rig it, and make it idle."
The assistant calls text_to_3d, polls generation_status, renders the result
as a live orbitable artifact, then auto_rig_model → apply_animation(animation: "idle") for a moving character.
Configuration
| Env | Purpose | Default |
|---|---|---|
REPLICATE_API_TOKEN |
Replicate lane for reconstruction, rigging, remesh, retexture, and the paid text→image backstop. Required for any mode with no GCP worker configured. | unset |
REPLICATE_RECONSTRUCT_MODEL |
image→3D model. | firtoz/trellis |
REPLICATE_TXT2IMG_MODEL |
Replicate text→image model for text_to_3d, used only after the free lanes (NVIDIA_API_KEY for NIM FLUX, GOOGLE_CLOUD_PROJECT for Vertex Imagen). |
black-forest-labs/flux-schnell |
REPLICATE_RERIG_MODEL |
Replicate auto-rig model, used when no GCP rig worker is configured. Without either, auto_rig_model reports "not configured". |
unset |
GCP_RECONSTRUCTION_KEY + per-mode worker URLs |
Self-hosted GCP workers, preferred over Replicate for every mode whose URL is set: GCP_RECONSTRUCTION_URL (reconstruct), GCP_UNIRIG_URL (rig), GCP_REMESH_URL, GCP_STYLIZE_URL, GCP_SEGMENT_URL, GCP_TEXTURE_URL (retexture; required for retexture_region), GCP_REMBG_URL, GCP_VIDEO2SCENE_URL (capture_scene). |
unset |
WATSONX_API_KEY / WATSONX_PROJECT_ID |
Enable direct_prompt + generate_material. |
— |
APP_ORIGIN |
Origin used to load the animation manifest for list_animations / apply_animation. |
request host |
MCP_POSE_PREVIEW_BASE |
Base URL for pose_model preview links. |
https://three.ws/pose |
Geometry backends (Meshy/Tripo) take a per-request key via the
x-forge-provider-key header — never an env var.
Rate limits: generation/rig/mesh jobs are capped per principal (real GPU spend);
status polling is capped per minute. pose_model, list_animations,
inspect_model, and optimize_model are lightweight.
Publishing to the MCP Registry
The manifest is server-3d.json. Publish with the
mcp-publisher CLI (the GitHub-namespace ownership flow proves control of the
io.github.nirholas/* namespace):
mcp-publisher login github
mcp-publisher publish --file server-3d.json
Or let the repo's publisher do it alongside the other servers, under the
remote-3d key: npm run publish:mcp:dry, then
npm run publish:mcp -- --only remote-3d.
Local development
npm run dev
npx @modelcontextprotocol/inspector http://localhost:3000/api/mcp-3d