@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

Solana & markets

Agents & identity

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)

Optional

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.

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}