Three MCP Server

three.ws

Website · X / Twitter · GitHub · $THREE on pump.fun

https://github.com/user-attachments/assets/d52515d1-cb04-4dd6-98bd-fef233312dc4

Give your AI a body. three.ws is an open-source, browser-native 3D AI agent platform. Type a prompt and Forge generates a textured 3D model — or drop a GLB you already have. Add an LLM brain, register on-chain, and embed anywhere — no plugins, no server uploads, no installs required.

Try it in 60 seconds: open three.ws/forge, type "a brass steampunk owl, full body", and download the GLB. Text→3D, image→3D, and sketch→3D — free draft tier, no account. Jump to the Forge section ↓

$THREE

$THREE is the native token of the three.ws ecosystem — the one and only coin of the platform.

Always verify the contract address above before trading. $THREE is the only token associated with three.ws.

---

Table of Contents

• What is three.ws?
• Vision
• Roadmap
• Key Features
• Forge — Text & Image to 3D
• Platform Pages
• Cloud Marketplaces
• Ecosystem Directories
• IBM watsonx & Granite
• Screenshots
• Architecture
  • Design Docs & Specs
• Tech Stack
  • Browser Support
• Getting Started
• Examples
• Tutorials
• Project Structure
• The Agent System
  • Event Bus (Agent Protocol)
  • LLM Runtime
  • Empathy Layer
  • Skills
  • Memory
• Web Component & Embedding
• Widget System
• Embed Editor
• Pose Studio
• Launchpad
• The Club
• Walk & Multiplayer
• Coin Communities
• City
• Friends, Presence & Social
• In-Game Economy
• Voice Lab & Mocap Studio
• x402 Payments
• A2A — Agent-to-Agent Protocol
• Talk Mode & Lip-Sync
• Solana Mobile (Seeker)
• Selfie Reconstruction Pipeline (Phase 1)
• Livepeer Inference Network (Phase 4)
• Voice & Persona Hub (Phase 2)
• WASM Vanity Grinder
• News CMS & Syndication
• Security Hardening
• Developer SDKs
• Claude Code Integration
• Demos Hub
• Skill Library
• Animation System
• Avatar Accessories & Coin Launchpad
• Brain Proxy & LLM Routing
• API Reference
• Authentication & OAuth 2.1
• MCP Server
• On-Chain Identity (ERC-8004 + Metaplex Core)
• Pump.fun Integration
• Database Schema
• Build & Deployment
  • Versioning & Compatibility
• Environment Variables
• Testing
• FAQ & Troubleshooting
• Contributing
• Contributors
• License

---

What is three.ws?

three.ws is a full-stack system for creating, deploying, and embedding 3D AI agents. It combines a WebGL model viewer, an LLM-driven agent runtime, on-chain identity contracts, and a distributable web component into one cohesive platform.

At its core, it does five things:

1. Generate — turns a text prompt, 1–4 photos, or a sketch into a textured, downloadable GLB via Forge. Free draft tier, no account required; auto-rigging, restyling, and retexturing in the same flow.

2. Render — loads and validates glTF 2.0 / GLB models in WebGL 2.0 with zero server-side processing. Drag a file onto the browser and it renders instantly with full Draco, KTX2, and Meshopt decompression.

3. Embody — wraps any avatar with an LLM brain. The agent listens to the user, thinks with Claude, executes tools (animations, gestures, memory operations, skill calls), and expresses emotion through morph-target blending on the 3D model in real time.

4. Register — optionally mints the agent on-chain: as an ERC-8004 token on any EVM chain, or as a Metaplex Core NFT on Solana. Either path gives the agent a stable on-chain identity, a wallet address, signed action history, and a reputation score that cannot be forged.

5. Embed — distributes the agent as an <agent-3d> web component that anyone can drop into a page, or as one of five purpose-built widget types (turntable, animation gallery, talking agent, passport card, hotspot tour) with Open Graph and oEmbed support built in.

The backend is a set of Vercel serverless functions backed by Neon Postgres for metadata, Cloudflare R2 for model storage, and Upstash Redis for rate limiting. It exposes a full OAuth 2.1 authorization server and an MCP (Model Context Protocol) endpoint so external AI systems can drive avatars programmatically.

three.ws is production-ready and serves three.ws live. The entire stack — viewer, agent runtime, contracts, backend, and web component — is open source under Apache 2.0.

---

Vision

One day, creating your agent should be as simple as taking a selfie.

Point your camera at yourself — or anyone — and watch a fully realized 3D avatar emerge: your face, your voice, your personality, alive in the browser. That avatar becomes an agent with memory and skills, registered onchain — as an ERC-8004 token on EVM or a Metaplex Core asset on Solana — permanent and verifiable by anyone forever. No 3D software. No wallet setup. No uploads. Just a photo and a name.

This is the direction three.ws is heading: photo → avatar → agent → onchain identity, in a single flow. The infrastructure is already here — the viewer, the runtime, the contracts, the embedding layer. What comes next is closing the gap between a picture of a person and a living, ownable, embeddable piece of them that exists on the internet permanently.

---

Roadmap

three.ws ships in four phases. Each phase closes a specific gap between the current platform and the end-state vision: anyone can mint a 3D agent of themselves, own it onchain, and embed it anywhere on the internet.

---

Phase 0 — Foundations (Shipped)

The full stack is live at three.ws: WebGL viewer, LLM agent runtime, ERC-8004 identity contracts (EVM) and Metaplex Core mints (Solana), OAuth 2.1 server, MCP endpoint, and the <agent-3d> web component. Anyone can register an agent today — but the avatar still has to come from a 3D artist or a third-party tool.

What works: model upload, agent runtime, onchain registration, embedding, signed action history, reputation scores. What doesn't: there is no automated path from a real human face to a usable 3D avatar.

---

Phase 1 — Selfie → Avatar Engine

Goal: any user takes 3 selfies (left, center, right) and receives a rigged, animatable 3D avatar in under 60 seconds.

Deliverables

• Mobile-first capture UX with realtime quality gates (lighting, framing, blur)
• Multi-view face reconstruction pipeline (FLAME / 3DMM fitting on top of a base body mesh)
• Hosted inference workers (GPU-backed) for sub-minute generation
• Output written directly to R2 and minted as a draft agent token — ERC-8004 on EVM, Metaplex Core asset on Solana

Compute requirements

• A100/H100-class GPUs for inference, sized to ~10k avatars/day at launch
• Training budget for fine-tuning a stylized face-fitter on a curated dataset
• CDN egress scaling for high-res GLB delivery

Verification: 1,000 test users complete capture and mint an onchain agent of themselves end-to-end with ≥4/5 likeness score.

---

Phase 2 — Agent Personalization

Goal: the avatar isn't just you — the agent acts like you.

Deliverables

• Voice cloning (3–10 seconds of speech → ElevenLabs custom voice bound to the agent)
• Persona extraction from a short onboarding interview (tone, vocabulary, interests)
• Memory seeding from connected accounts (X, GitHub, Farcaster) with explicit user consent
• Per-agent fine-tuned system prompt stored in the manifest, signed and pinned to IPFS

Verification: users return to converse with their own agent; ≥30% week-2 retention on minted agents.

---

Phase 3 — Onchain Economy

Goal: agents are real economic objects on EVM and Solana, not just collectibles.

Deliverables

• Agent tokens — ERC-8004 mints with bonding-curve pricing or fair launch options
• Reputation markets — stake on agents, earn from their action history (extends ReputationRegistry.sol)
• Skill royalties — skill authors earn per-call fees through EIP-7710 delegated permissions
• Agent-to-agent payments — agents transact autonomously via their delegated signer wallets
• Subscriptions & DCA — recurring onchain payments to creators (cron infra already in place)

Funding requirements

• Smart contract audits (multi-firm) for the reputation, royalty, and delegation contracts
• Liquidity for agent token launches
• Indexer infrastructure across Base, Solana, and additional EVM chains

Verification: ≥1,000 agents minted with active onchain reputation; ≥$X in cumulative skill royalties paid out.

---

Phase 4 — Open Inference Network

Goal: decouple agent inference from any single provider. Anyone can run a node; agents pay nodes onchain for compute.

Deliverables

• Open protocol for agent inference (model weights, GPU runtime, signed responses)
• Node operator client (Docker + GPU drivers) with onchain registration
• Onchain settlement for inference jobs — pay-per-token with cryptographic receipts
• Federation with existing decentralized compute networks where appropriate

Compute requirements

• Bootstrap GPU credits for early node operators
• Cryptoeconomic security model (slashing, validator set) — research + audit budget

Verification: ≥50% of production agent traffic served by independent node operators; latency parity with centralized inference.

---

What we need

Phases 1 and 2 unblock the consumer story — anyone gets an agent of themselves. Phases 3 and 4 unblock the onchain story — those agents are real economic actors that don't depend on any one company to keep running. Both are required for the vision; neither is funded yet.

If you want to support the project — compute credits, grants, partnerships, or contributions — open an issue or reach out via three.ws.

---

Key Features

Text → 3D Generation (Forge)

• Prompt-to-3D at three.ws/forge — describe an object in a sentence and download a textured GLB
• Image→3D (one to four photos) and sketch→3D in the same composer
• Multiple generation engines with live health checks: self-hosted lanes plus bring-your-own-key Meshy and Tripo (keys stay in the browser)
• Prompt-to-avatar at three.ws/create/prompt — a description becomes a rigged, animatable 3D avatar
• Generated models carry straight into Scene Studio, embeds, worlds, and on-chain deployment

3D Viewer

• WebGL 2.0 rendering via three.js r184
• glTF 2.0 and GLB with Draco geometry compression, KTX2 texture compression, and Meshopt mesh optimization
• Khronos-spec glTF validation with line-level error reporting
• HDR environment maps, PBR materials, skinned mesh animations, morph targets, and embedded cameras
• OrbitControls (pan, zoom, rotate) with configurable auto-rotation
• Real-time parameter tweaking (lights, exposure, morph weights) via dat.GUI

Agent Runtime

• LLM brain powered by Claude (Anthropic API) with a structured tool-loop architecture
• Up to 8 tool iterations per turn before returning final output
• Built-in tools: wave, lookAt, play_clip, setExpression, speak, remember
• Composable skill system — install skills from IPFS, Arweave, or HTTP; each skill is a self-contained bundle with a description, tool definitions, and async handlers
• Weighted emotion blending (celebration, concern, curiosity, empathy, patience) driven by protocol events, not a finite-state machine
• Web Speech API for STT/TTS out of the box; ElevenLabs integration for production-quality voice
• Talk mode with audio-driven ARKit-52 lip-sync — TTS audio is analysed in real time and drives 52 standard blendshapes on the avatar
• Anonymous Groq-powered chat for unauthenticated visitors; owner-card gating when an agent has a paying author

x402 Payments & Bazaar

• Native x402 paid endpoints on Base, BSC, and Solana — agents pay other agents in USDC for API calls, asset downloads, and skill royalties
• Coinbase CDP facilitator on Base mainnet; direct-scheme payments on BSC
• Permit2 gas-sponsoring siblings on every CDP-settled endpoint (buyer signs, relayer pays gas)
• Pay-by-name — /api/x402/pay-by-name resolves @username, *.sol (incl. subdomains), or raw base58 to a recipient and builds an unsigned USDC transfer for the payer's wallet. Every 402 manifest emitted by a named agent advertises recipient_name next to the wallet, so payers verify a human-readable name before signing
• SKU catalog + Stripe-style checkout at /dashboard/x402; receipts ledger with admin tooling
• Subscriptions, idempotency tokens, offer receipts, paid asset download, and a bazaar listing/search API
• SIWX (Sign-In with X-chain) server for auth-gated paid endpoints
• Listed on x402scan and the MCP Registry

SNS / *.threews.sol subdomains

• /threews/claim lets any signed-in user mint [username].threews.sol in a single atomic Solana transaction — createSubdomain → URL record → transferSubdomain to the user's wallet, with three.ws absorbing gas
• Brave Browser resolves the subdomain directly to the user's /u/[username] showcase via the SNS URL record
• Agents can bind a .sol name (theirs or a fresh registration) via /api/agents/:id/sns; once bound, every public surface — agent page, x402 manifest, MCP listing, marketplace card — displays the name in place of the raw wallet
• See docs/internal/SNS_PARTNERSHIP_PROPOSAL.md for the partnership pitch to Bonfida

A2A — Agent-to-Agent Protocol

• A2A client + server, MCP bridge, DID resolution, spending ledger, receipts storage
• Agents transact autonomously via their delegated signer wallets and EIP-7710 permissions

Identity & On-Chain

• ERC-8004 smart contracts (IdentityRegistry, ReputationRegistry, ValidationRegistry) deployable on any EVM chain — plus a program-free Metaplex Core analog on Solana (asset pubkey = agent ID, SPL Memo–anchored reputation + validation attestations)
• Each agent is an ERC-721 token with a stable agentId, owner wallet, delegated signer (EIP-712), and IPFS-pinned manifest
• Signed action log — every speak, remember, skill-done, and validate event is recorded on-chain-optionally or in the database with a cryptographic signature
• EIP-7710 delegated permissions for composable agent-to-agent authorization
• Solana support (SIWS sign-in, Solana wallet linking, Metaplex NFT option)

Embedding & Distribution

• <agent-3d> custom element — drop it anywhere with no framework dependency
• Five widget variants: turntable, animation gallery, talking agent, ERC-8004 passport card, hotspot tour
• Widget Studio + WYSIWYG Embed Editor at /embed-editor — pick an avatar, animation, framing, and background, copy the snippet
• Launchpad at /launchpad — hosted public launch pages at /p/[slug] for tokens, agents, and drops
• Open Graph metadata and oEmbed support for rich social previews when links are shared
• Versioned CDN bundles at /agent-3d/x.y.z/agent-3d.js

Social & Multiplayer 3D

• Coin Communities at /communities + /play — every Solana token gets a live 3D world; pick the same coin and land together, with peer avatars, chat, emotes, voxel building, and a live market-cap screen
• City at /city — free-roam walkable 3D city scene
• Friends, presence & DMs — account-level social graph with live presence ("Online · Mainland"), direct messages, and a per-account realtime delivery hub
• The Club at /club — multiplayer venue with rigged dancers, audio tracks, tips, leaderboard, payouts cron, perf-aware renderer that auto-downgrades on slow frames
• Walk at /walk — authoritative multiplayer walk scene backed by a Colyseus server in multiplayer/ (deployable on Fly.io)
• Pose Studio at /pose-studio, Voice Lab at /voice, Mocap Studio at /mocap-studio — author poses, bind voices, and capture/retarget motion into reusable clips

Backend & Integrations

• OAuth 2.1 server (RFC 6749 + PKCE, RFC 7591 dynamic registration, RFC 7009 revocation, RFC 7662 introspection, RFC 8414 discovery)
• Developer API keys with scope and expiry
• MCP (Model Context Protocol) over HTTP with JSON-RPC 2.0 for tool-calling from external AI systems; A2A bridge exposes paid tools as x402 endpoints
• Avaturn (photo-to-avatar), Character Studio (in-browser builder), Avatar Studio (rebranded marketplace), and Privy (embedded wallet) integrations
• Replicate-backed avatar regeneration provider for photo-to-avatar workflows
• Native selfie reconstruction pipeline (Phase 1) + Livepeer inference network (Phase 4) wired into the agent runtime
• DCA strategy execution and on-chain subscription scheduling via cron jobs
• News CMS at /admin/news with multi-destination syndication (WebSub, Dev.to, Medium, HackerNoon, CMC handoff)
• Solana Mobile (Seeker) MWA wallet wired into the web app + Solana Mobile dApp Store release pipeline
• Hardened API surface: SSRF guard, CSRF gates, header-origin pinning, fail-closed crons
• OpenAPI 3.1 spec generated at /openapi.json

---

Forge — Text & Image to 3D

Type a sentence, get a 3D model. Forge turns a text prompt, one to four photos, or a rough sketch into a textured, downloadable GLB — in the browser, with a free draft tier and no account required.

Three quality tiers — draft (~12k polygons), standard (~30k, default), high (~200k + PBR textures) — and two generation paths: the platform-keyed image pipeline (FLUX → TRELLIS) that works with no key at all, and bring-your-own-key native geometry via Meshy or Tripo for the cleanest quad topology (your key stays in your browser).

Forge is not a dead end. Every generated model carries straight into the rest of the platform: open it in Scene Studio, auto-rig it into an animatable character, restyle it (voxel / brick / voronoi / low-poly), retexture it from a prompt, embed it with <agent-3d>, give it an LLM brain, or deploy it on-chain. Prompt-to-avatar lives at three.ws/create/prompt — a description becomes a rigged, animatable agent body.

REST API

The same engine is one HTTP call, free and auth-free:

# Submit a text→3D job
curl -X POST https://three.ws/api/forge \
  -H 'content-type: application/json' \
  -d '{"prompt": "a brass steampunk owl, full body", "tier": "standard"}'
# → { "job_id": "…", … }

# Poll until done
curl 'https://three.ws/api/forge?job=<job_id>'
# → { "status": "done", "glb_url": "https://…/model.glb", … }

Image→3D is the same endpoint with image_urls: ["https://…/front.png", …] (1–4 views) instead of a prompt. GET /api/forge?catalog returns the live tier/backend/cost matrix.

From Claude, Cursor, or any MCP client

The 3D Studio MCP server at https://three.ws/api/mcp-3d exposes the full pipeline as 15 tools — text_to_3d, image_to_3d, auto_rig_model, apply_animation, stylize_model, retexture_model, segment_model, and more — so an AI assistant can generate, rig, and animate a model mid-conversation and render it as an inline interactive artifact. See docs/mcp-3d-studio.md.

Pay-per-call for autonomous agents (x402)

POST /api/x402/forge is the monetized twin: agents pay per generation in USDC on Base or Solana — no API key, no account. Draft $0.05, standard $0.15, high $0.50; polling is free; retried payments are idempotent and never double-charge. See docs/api/forge-x402.md.

Learn more

• Tutorial: Turn a Text Prompt into a 3D Model — first model in about a minute
• Tutorial: Turn Photos into a 3D Model — reconstruct a real object from 1–4 photos
• 3D Studio MCP server — generate from inside Claude or Cursor
• Paid generation API (x402) — autonomous agent-to-agent generation

---

Platform Pages

A map of every user-facing route. Full detail (source files, feature descriptions, hash-routes) is in docs/internal/PAGES.md.

---

Cloud Marketplaces

three.ws is available on major cloud marketplaces and open to infrastructure partnerships.

Ecosystem Directories

three.ws is indexed in chain-ecosystem dApp directories so the community can discover, vet, and rank it.

---

IBM watsonx & Granite

three.ws is an IBM Business Partner, and the agent runtime runs on IBM Granite foundation models served through IBM watsonx.ai. One IBM Cloud API key + project unlocks the whole suite; every call is real inference (no mock path — endpoints return 503 when unconfigured). Full docs: docs/ibm.md. Live showcase: three.ws/ibm/galaxy.

The public showcase is not the partnership. The demos under /ibm/* are independent tools three.ws built for developers to explore Granite on watsonx.ai and build their own integrations — they are not official IBM partnership deliverables, not IBM products, and not endorsed by IBM. Our formal partnership work with IBM is being built on the IBM platform and is not yet public.

Six showcase surfaces put it on screen, cross-linked by an in-page suite switcher: the Agent Galaxy (semantic 3D star-map), the Granite Oracle (narrated forecast), the Digital Twin (back-test + what-if), the Trust Layer (Guardian + hash-chained audit ledger), Granite Proof (a Guardian-governed forecast notarized on Solana), and Granite Vision. The standalone connector @three-ws/ibm-watsonx-mcp exposes watsonx.ai to any MCP host — it is community-built and not an IBM product; the hosted platform integration is what runs on IBM watsonx.ai.

Pay-per-call Granite over MCP (x402)

The world's first x402-enabled MCP server on IBM Cloud: @three-ws/ibm-x402-mcp turns IBM Granite into a metered utility any AI agent can call. The operator holds the IBM credentials and funds inference; the caller pays a few cents of USDC per call — no IBM Cloud account, no subscription, no API-key signup. Full guide: docs/ibm-x402-mcp.md.

The same five tools ship over two transports: stdio (npx @three-ws/ibm-x402-mcp, for Claude Desktop / Code / Cursor, paid on Solana) and Streamable HTTP (https://three.ws/api/ibm-mcp, for hosted clients and watsonx Orchestrate, paid on Base or Solana). An unpaid tools/call returns a 402 quoting the exact USDC price; x402-capable clients pay and retry automatically, settling on-chain only after the tool succeeds. Independent project integrating IBM Granite via watsonx.ai — not an IBM product.

---

Screenshots

---

Architecture

The platform is organized into four layers. All layers communicate through a single event bus (agent-protocol) rather than direct calls.

Documentation truncated — see the full README on GitHub.