@three-ws/mcp-server

MCP tools from three.ws — free text→3D plus paid text/image→3D, avatars, rigging, agent reputation, and more. Paid calls settled per call in USDC.

Quickstart · Tools · Config · Programmatic · Payments · three.ws

---

MCP tools from three.ws, five need no payment, wallet, or API key to start: forge_free (text prompt → 3D GLB on the free NVIDIA NIM / Microsoft TRELLIS lane), vanity_premium (browse the pre-ground premium vanity inventory), and the crypto-news trio (crypto_news, crypto_news_digest, and crypto_news_archive, archive search is free up to a daily quota, then $0.001 USDC per search via x402). The rest are paid: text/image→3D mesh generation, 3D avatars, one-call text→rigged-avatar generation, GLB auto-rigging, conversational model refinement, material restyling, pose seeds, pump.fun snapshots, ERC-8004 agent reputation, ENS/SNS resolution, agent-to-agent delegation and end-to-end agent hiring, token sentiment, AgenC coordination reads, aixbt market intel, and a Solana vanity grinder. Paid calls are settled in USDC via the x402 payment protocol on Solana mainnet (exact scheme). No subscription, no API key, pay per call, and failed calls never bill the caller.

---

Quickstart (30 seconds)

Claude Code

claude mcp add 3d-agent -- npx -y @three-ws/mcp-server

To also receive payments (server operators), pass the payout address as env: claude mcp add 3d-agent -e MCP_SVM_PAYMENT_ADDRESS=YourSolanaWallet -- npx -y @three-ws/mcp-server.

Claude Desktop

Paste this into your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
	"mcpServers": {
		"3d-agent": {
			"command": "npx",
			"args": ["-y", "@three-ws/mcp-server"],
			"env": {
				"MCP_SVM_PAYMENT_ADDRESS": "YourSolanaWallet"
			}
		}
	}
}

Restart Claude Desktop. All tools appear immediately — no install step required.

---

Tools

All 25 tools are listed below. Most quote a fixed USDC price and settle exact on Solana mainnet (prices below come straight from each tool's source); forge_free, vanity_premium, crypto_news, and crypto_news_digest are free, no payment, no wallet, no API key, and crypto_news_archive search is free up to a daily quota (stats/trending always free). Every tool also declares MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so clients can scope confirmation prompts correctly, none of these tools are destructive.

3D generation

Tool	Price	What it returns
forge_free	Free	Textured 3D GLB from a text prompt — at zero cost. Drives the three.ws /api/forge pipeline on the free NVIDIA NIM (Microsoft TRELLIS) text→3D lane — the same engine the /forge web page uses for prompt drafts. No x402 payment, no wallet, no API key. Pick tier draft (fast, default), standard, or high — all free. Returns the durable glbUrl, a three.ws viewer preview link, the tier, and the backend that actually ran. Text-only; for image/multi-view input or the Granite-directed chain use mesh_forge. Feed the glbUrl to rig_mesh to animate it.
mesh_forge	$0.25	Textured 3D GLB from a text prompt or a reference image. Text mode runs a chain of specialist models — an IBM Granite "prompt director" rewrites the prompt into an optimized single-subject 3D spec, FLUX renders a reference image, and Microsoft TRELLIS / Tencent Hunyuan3D reconstruct the mesh. Image mode (image_url) reconstructs directly. Returns the durable glbUrl, a three.ws viewer preview, the directedPrompt, and timing.
rig_mesh	$0.20	Auto-rig a static GLB into an animation-ready model: humanoid skeleton + per-vertex skin weights via Make-It-Animatable. Takes a glb_url (e.g. mesh_forge's output), returns the riggedGlbUrl and a three.ws pose-studio link.
forge_avatar	$0.45	Text/image → rigged, animation-ready avatar in ONE call. Chains the whole pipeline: Granite prompt director → FLUX + TRELLIS/Hunyuan3D reconstruction → Make-It-Animatable rigging, so the result loads straight into the pose studio and plays the canonical idle/walk library. Takes a prompt, a single image_url, or 1-4 image_urls (front/back/left/right) for higher-fidelity multi-view. A humanoid gate rejects a clearly non-humanoid subject without charge (use mesh_forge / forge_free for those, or set allow_non_humanoid). Returns the rigged GLB, the intermediate mesh, a pose-studio link, the directed prompt, and per-stage timing.
text_to_avatar	$0.15	Textured 3D GLB avatar from a text prompt or reference image URLs, driving Replicate (Hunyuan-3D 3.1 by default). Returns the GLB URL, model version, prediction id, and timing.
refine_model	$0.25	Iterate on a model by describing a change in plain language ("make it metallic", "bigger helmet"). Re-generates a new version anchored to the previous one (the prior prompt is folded with your change; an optional reference image anchors it as image→3D): real generation, never a fake diff. Each refinement appends to an immutable parent→child version lineage, so you can branch from an earlier version (parent_index) or revert. Pass parent_lineage to extend a thread. Returns the new GLB, a viewer link, the composed prompt, the lineage, and the active version index.
restyle_material	$0.05	Re-skin an existing GLB without regenerating its mesh (geometry and UVs preserved exactly). Two modes: instruction ("make it chrome", "cyberpunk neon") for an AI-proposed PBR material, or preset (+ seed/count) for N reproducible colorway variants: same preset + seed always yields the same set. Shares refine_model's lineage, so a restyle is just another version; the source GLB is never modified. Returns durable GLB URL(s), the applied PBR factors, and the lineage.
get_pose_seed	$0.001	Deterministic seed + full Euler-rotation pose map (radians) for the three.ws pose-studio mannequin, matched from the in-repo preset library. Includes a previewUrl at https://three.ws/pose?seed=…&preset=….

Solana & markets

Tool	Price	What it returns
pump_snapshot	$0.005	Live token snapshot — USD price (Jupiter), 24h volume + pair (Dexscreener), mint metadata + image (pump.fun frontend-api-v3), and on-chain top-holder distribution (Solana RPC). Adds Helius DAS data when HELIUS_API_KEY is set.
sentiment_pulse	$0.003	Sentiment for a Solana token: scores the coin's recent pump.fun callouts (plus optional caller-supplied snippets) with the three.ws deterministic lexicon. Returns overall + per-source breakdown with examples. Pairs with pump_snapshot.
vanity_grinder	$0.05	Solana keypair whose base58 address starts with prefix (and optionally ends with suffix). Returns the full base58 secret key — treat as a secret. Flat price (override with MCP_VANITY_PRICE_USD); a difficulty guard rejects prefixes too long to mine within the iteration cap.
vanity_premium	FREE	Browse the premium vanity inventory: long (4-5+ char) brandable Solana addresses ground ahead of time on batch CPU and sold from stock, which the live grinder cannot reach. Read-only and free: returns each address, its rarity tier, a difficulty-scaled price ($1-$50), and a ready-to-pay x402 buyUrl. Paying that URL (USDC on Base or Solana) reveals the private key exactly once; the ciphertext is destroyed on delivery. Filter by prefix or tier, sort by rarity/price/newest. Keys are platform-generated: use as a token mint or sweep to self-generated custody, not as a treasury.
aixbt_intel	$0.01	aixbt narrative intelligence feed — recent intel items across crypto with category, description, observation count, official-source flag, and the project/ticker concerned. Optional category/chain filter. Live aixbt REST API.
aixbt_projects	$0.01	aixbt momentum scan — projects ranked by spiking/climbing/active scores, with ticker, chain, market metrics (price, mcap, 24h volume + change), and recent intel. Filter by names or chain. Live aixbt REST API.
crypto_news	FREE	Live crypto headlines aggregated natively by three.ws from 197 publisher RSS/Atom feeds in 17 languages. Filter by category, source, or language, or full-text search. Each article carries the publisher link, publish time, detected tickers, and lexicon sentiment. No payment, no key.
crypto_news_digest	FREE	The last 1–72h of coverage clustered into distinct narratives — title, plain-language summary, bullish/bearish stance, tickers, coverage count, and every real article behind each story. Names its engine honestly (llm semantic grouping or heuristic Jaccard clustering). No payment, no key.
crypto_news_archive	FREE tier	Search 660,000+ archived articles back to September 2017 (refreshed hourly) by keyword, ticker, source, date range, sentiment, or language — with market context at publication where captured. mode: stats and mode: trending for corpus statistics and most-covered tickers (always free, no key). Search has a free daily quota (60/day per IP), then $0.001 USDC per search via x402 on the HTTP API; an exhausted quota returns a payment_required envelope with the price and networks.

Agents & identity

Tool	Price	What it returns
agent_reputation	$0.01	ERC-8004 reputation: getReputation, getTotalStake, and the latest ReputationSubmitted / ReputationStaked events from the canonical ReputationRegistry on the requested chain (default Base). Resolves agentId from a wallet address automatically.
agent_delegate_action	$0.01	Send a message to a three.ws-registered agent and receive its response (it uses its configured Claude model + system prompt). Agents opted out of MCP delegation are refused. For agent-to-agent collaboration and tool composition.
agent_hire_discover	$0.01	Step one of the commerce loop. Shortlist three.ws agents to hire for a task, ranked by task fit + live ERC-8004 on-chain reputation + real engagement. Each candidate carries its reputation evidence, capability/task-match score, and the exact USDC price agent_hire will settle. Optionally gate by a minimum reputation.
agent_hire	$0.05	Step two. Hire an agent end to end: quote the price up front, settle real USDC via x402, run the remote agent, and return its result plus a provenance receipt (agent, reputation, amount paid, on-chain settlement reference, latency) rendered as an inline MCP Apps receipt card. Enforces hard spend caps (per-call MCP_AGENT_HIRE_MAX_PER_CALL_USD, per-session ..._PER_SESSION_USD), a confirm threshold, and an optional reputation floor: a blocked or failed hire never charges the caller. Needs MCP_AGENT_TALK_TOKEN.
ens_sns_resolve	$0.0005	Resolve a human-readable name across ENS (.eth → Ethereum address via ethers) and SNS (.sol → Solana owner wallet via Bonfida, plus the wallet's other owned .sol domains). Suffix-less names are tried against both.
agenc_list_tasks	$0.001	List every public AgenC task created by a Solana wallet — task PDA, state, reward, deadline, worker counts, reward mint. AgenC (agenc.tech, Tetsuo Corp) is a Solana task-coordination protocol. cluster defaults to mainnet.
agenc_get_task	$0.001	On-chain state + lifecycle timeline of a single AgenC task. Pass taskPda or {creator, taskId} (hex or any UTF-8 label). Returns state, reward, deadline, worker counts, lifecycle events, reward mint.
agenc_get_agent	$0.001	An AgenC agent's on-chain registration. Pass agentPda or agentId (hex or UTF-8 label). Returns authority wallet, capability bitmask, endpoint URL, status, reputation, stake, and active task count.

---

Installation

The server runs locally on your machine and speaks stdio JSON-RPC — your MCP client spawns it automatically via the npx command above. You do not need to npm install globally.

If you prefer a global install:

npm install -g @three-ws/mcp-server

Then replace "command": "npx", "args": ["-y", "@three-ws/mcp-server"] with "command": "3d-agent-mcp" in your config.

---

Environment variables

Payout (set this to receive payments yourself)

Var	Description
MCP_SVM_PAYMENT_ADDRESS	Solana USDC payout address (base58) where tools receive payment. Falls back to X402_PAY_TO_SOLANA / X402_PAY_TO. If unset, the server still boots and routes paid-call USDC to the three.ws platform payout — set this to a 32–44 char base58 wallet to collect payments yourself. A configured-but-malformed address fails fast.

Optional

Var	Default	Description
HELIUS_API_KEY	unset	Adds Helius DAS enrichment to pump_snapshot
SOLANA_RPC_URL	https://api.mainnet-beta.solana.com	Primary Solana RPC for pump_snapshot / AgenC reads
SOLANA_RPC_URLS	built-in public set	Failover — comma-separated Solana RPCs tried in order; first healthy one answers
MCP_EVM_RPC_<chainId>	built-in public set	Failover — comma-separated EVM RPCs for that chain (agent_reputation, ENS uses chain 1)
X402_FACILITATOR_URL_SOLANA	https://facilitator.payai.network	Primary PayAI Solana facilitator that verifies + settles payments
X402_FACILITATOR_URLS_SOLANA	unset	Failover — comma-separated facilitators; earlier entries take precedence at init, a later one covers an outage
X402_FACILITATOR_TOKEN_SOLANA	unset	Bearer token for the Solana facilitator, if required
X402_FEE_PAYER_SOLANA	three.ws default	Fee payer for the settlement transaction
MCP_VANITY_PRICE_USD	$0.05	Flat price for vanity_grinder
FORGE_FREE_API_BASE	https://three.ws	three.ws origin the free forge_free tool calls (/api/forge)
FORGE_FREE_TIMEOUT_MS	180000	forge_free poll budget before it returns a resumable timeout
FORGE_FREE_POLL_MS	3000	forge_free poll interval while a queued job runs
FORGE_FREE_ATTEMPTS	2	Max forge_free generations to prefer a durable result when the NVIDIA lane degrades (1–4). It never returns a confirmed-dead URL as success
MCP_REVIEW_SECRET	unset	Review entitlement. When set, a caller presenting a matching MCP_REVIEW_MODE runs paid tools for real with no charge (connector-review access). Off unless set — never bypassable on a normal install
MCP_REVIEW_MODE	unset	Client-side value that must equal the server's MCP_REVIEW_SECRET to activate the review entitlement above
MCP_POSE_PREVIEW_BASE	https://three.ws/pose	Base URL for get_pose_seed preview links
MCP_AGENT_TALK_TOKEN	unset	Platform service credential (api_keys bearer, scope agents:delegate) the agent_hire / agent_delegate_action tools present to /api/agents/talk. That endpoint burns platform LLM credit and requires a principal — without this token a paid hire's delegation 401s and the x402 payment cancels (the hire cannot deliver). Falls back to THREE_WS_MCP_TOKEN / MCP_SERVICE_TOKEN
MCP_AGENT_HIRE_PRICE_USD	$0.05	The platform delegation fee agent_hire settles per hire
MCP_AGENT_HIRE_MAX_PER_CALL_USD	$1	Hard per-call spend cap — a hire above this is refused before any payment
MCP_AGENT_HIRE_MAX_PER_SESSION_USD	$5	Cumulative per-session spend cap across one connection
MCP_AGENT_HIRE_CONFIRM_THRESHOLD_USD	$0.50	Hires at or above this require an explicit confirm: true
MCP_AGENT_HIRE_MIN_REPUTATION	0	Default ERC-8004 reputation floor for hires (0 = don't gate; a caller can raise it per call)
MCP_AGENT_REP_RPC_<chainId>	public RPC	Per-chain RPC override for agent_reputation (tried before the failover set)
MCP_AGENT_REP_LOG_WINDOW	200000	Block window for agent_reputation event scan
X402_ASSET_MINT_SOLANA	USDC (EPjFW…Dt1v)	SPL mint settled as the payment asset (defaults to Solana USDC)
SOLANA_DEVNET_RPC_URL	public devnet	Devnet RPC for the AgenC tools when cluster: "devnet"
AGENC_RPC_URL	unset	Single-endpoint override for all AgenC reads (wins over cluster defaults)
MCP_ENS_RPC_URL / MAINNET_RPC_URL	failover set	Ethereum-mainnet RPC override for ens_sns_resolve
MESH_FORGE_TIMEOUT_MS / MESH_FORGE_POLL_MS	180000 / 3000	mesh_forge reconstruct poll budget / interval
MESH_FORGE_DIRECTOR	1 (on)	Set 0 to skip the IBM Granite prompt-director stage in mesh_forge
RIG_MESH_TIMEOUT_MS / RIG_MESH_POLL_MS	180000 / 3000	rig_mesh poll budget / interval

text_to_avatar (Replicate)

The text_to_avatar tool drives Replicate. If the two vars below are unset it returns a not_configured error instead of generating — every other tool works without them.

Var	Default	Description
REPLICATE_API_TOKEN	unset (required)	Replicate API token used to submit the prediction
REPLICATE_TEXT_TO_AVATAR_MODEL	unset (required)	Pinned commercial-OK image/text-to-3D version hash (e.g. Hunyuan-3D 3.1)
MCP_TEXT_TO_AVATAR_TIMEOUT_MS / MCP_TEXT_TO_AVATAR_POLL_MS	110000 / 2000	Prediction poll budget / interval
MCP_TEXT_TO_AVATAR_REHOST	0	Set 1 to rehost the Replicate GLB to three.ws R2 via MCP_REHOST_ENDPOINT + MCP_REHOST_KEY

---

Programmatic client

Use @x402/mcp's wrapMCPClientWithPayment to call these tools from another Node service. The wrapper auto-handles 402 retries:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { wrapMCPClientWithPayment } from '@x402/mcp';
import { x402Client } from '@x402/core/client';
import { registerExactSvmScheme } from '@x402/svm/exact/client';
import { Keypair } from '@solana/web3.js';
import bs58 from 'bs58';

const transport = new StdioClientTransport({
	command: 'npx',
	args: ['-y', '@three-ws/mcp-server'],
	env: {
		// Where the server receives USDC. Your client funds payments from the
		// Solana keypair below.
		MCP_SVM_PAYMENT_ADDRESS: process.env.MCP_SVM_PAYMENT_ADDRESS,
	},
});

const mcp = new Client({ name: 'agent', version: '1.0.0' });
await mcp.connect(transport);

// Solana mainnet, `exact` scheme — the only network/scheme these tools accept.
const payer = Keypair.fromSecretKey(bs58.decode(process.env.AGENT_SOLANA_SECRET_KEY));
const x402 = new x402Client();
registerExactSvmScheme(x402, { signer: payer });
const paid = wrapMCPClientWithPayment(mcp, x402, { autoPayment: true });

const result = await paid.callTool('get_pose_seed', { prompt: 'warrior stance' });
// Prefer MCP structured output; fall back to the text mirror for older servers.
console.log(result.structuredContent ?? JSON.parse(result.content[0].text));

forge_free needs no payer — it never emits a 402 — so you can call it on the bare MCP client (the one before wrapMCPClientWithPayment):

// Free text → 3D — no wallet, no payment, no API key.
const free = await mcp.callTool('forge_free', { prompt: 'a glossy white robot mascot', tier: 'draft' });
const out = free.structuredContent ?? JSON.parse(free.content[0].text);
console.log(out.glbUrl, out.preview); // durable GLB + in-browser viewer link

---

Cursor

In Cursor's MCP settings (Cursor > Settings > Features > MCP):

{
	"mcpServers": {
		"3d-agent": {
			"command": "npx",
			"args": ["-y", "@three-ws/mcp-server"],
			"env": {
				"MCP_SVM_PAYMENT_ADDRESS": "YourSolanaWallet"
			}
		}
	}
}

---

Run from source

From the monorepo root:

npm install
node mcp-server/src/index.js

Inspect tools interactively:

npm run inspect --prefix mcp-server

Examples

Runnable walkthroughs of the MCP Streamable HTTP lifecycle against the live three.ws server (curl and plain-fetch Node, zero dependencies) live in examples/.

---

Payment flow

The server is the x402 resource server. On each tool call:

1. Client sends a tools/call request (no payment yet).
2. Server returns PaymentRequired (v2 MCP transport spec) with the USDC amount and payment address.
3. A payment-aware client (or wrapMCPClientWithPayment) signs and submits the on-chain payment.
4. Client retries the tools/call with _meta["x402/payment"] attached.
5. Server verifies + settles via the configured facilitator, runs the tool, and returns the result with _meta["x402/payment-response"].

Every tool settles in USDC on Solana mainnet with the exact scheme (@x402/svm ships no upto/metered scheme). Each tool quotes a fixed price; there is no post-hoc metering.

A successful result carries the tool's JSON in two forms: content[0].text (for text-only clients) and structuredContent (MCP 2025-06-18 structured output — a ready-to-use object). A tool-level error sets isError: true, and the x402 wrapper cancels rather than settles the payment, so failed calls do not bill the caller.

---

Reliability & failover

Every external dependency has a backup path, so a single provider blip doesn't take a tool down — and no call can hang a paid request indefinitely.

• Every outbound HTTP call runs through a shared resilient layer (src/lib/resilient-fetch.js): a hard per-attempt timeout plus jittered exponential-backoff retries on transient 429/5xx/network errors, honoring Retry-After. Retries are restricted to idempotent reads by default — a non-idempotent action like agent_delegate_action gets the timeout but is never silently replayed.
• Solana RPC (src/lib/solana-rpc.js) fails over across an ordered endpoint list (SOLANA_RPC_URLS, else the primary, else a built-in public set). A throttling or down endpoint rotates to the back and the next one answers.
• EVM RPC (src/lib/evm-rpc.js) uses an ethers FallbackProvider (quorum 1) over multiple endpoints per chain (MCP_EVM_RPC_<chainId> or built-in redundancy), each request timeout-bounded.
• The x402 facilitator accepts a comma-separated X402_FACILITATOR_URLS_SOLANA: earlier entries take precedence at init, and a later facilitator covers the Solana exact kind if the primary's /supported is unreachable.
• Data fallback: pump_snapshot cross-fills its USD price from Dexscreener when Jupiter is unavailable, and each upstream fails soft to a null/{ error } field rather than failing the whole snapshot.

For maximum redundancy, set dedicated endpoints rather than relying on the public defaults:

SOLANA_RPC_URLS="https://your-primary-rpc,https://your-secondary-rpc"
MCP_EVM_RPC_8453="https://your-base-rpc,https://base-rpc.publicnode.com"
X402_FACILITATOR_URLS_SOLANA="https://facilitator.payai.network,https://your-backup-facilitator"

---

Architecture

┌─────────────────┐     ┌─────────────────────┐     ┌──────────────────────┐
│ Claude Desktop  │────▶│ @three-ws/mcp-server │────▶│  x402 facilitator    │
│  / Cursor /     │     │   (stdio transport) │     │  (PayAI — Solana     │
│  your agent     │     │                     │     │   USDC, exact)       │
└─────────────────┘     └─────────────────────┘     └──────────────────────┘

Source: mcp-server/

---

Requirements

• Node.js >= 20 (from engines).
• A Solana USDC payout address in MCP_SVM_PAYMENT_ADDRESS (or X402_PAY_TO_SOLANA / X402_PAY_TO) to settle paid calls — see Environment variables. Tool registration (names/schemas) needs no env; only an actual paid invocation does.
• A payment-aware MCP client (or @x402/mcp's wrapMCPClientWithPayment) funding payments from a Solana keypair.

Related

• @three-ws/pumpfun-mcp — the free, read-only pump.fun + Solana MCP (token discovery, on-chain analysis, live 3D snapshots; no keys).

Links

• Homepage: https://three.ws
• Changelog: https://three.ws/changelog
• Issues: https://github.com/nirholas/three.ws/issues
• License: Apache-2.0 — see LICENSE

---

_{Part of the three.ws SDK suite — 3D AI agents, on-chain identity, and agent payments.
Website · Changelog · GitHub}