Name	Name	Last commit message	Last commit date
parent directory ..
src	src
LICENSE	LICENSE
README.md	README.md
package.json	package.json
server.json	server.json

@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

Sixteen MCP tools from three.ws — one free (forge_free: text prompt → 3D GLB on the free NVIDIA NIM / Microsoft TRELLIS lane, no payment and no API key) and fifteen paid: text/image→3D mesh generation, 3D avatars, GLB auto-rigging, pose seeds, pump.fun snapshots, ERC-8004 agent reputation, ENS/SNS resolution, agent-to-agent delegation, 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. Alternatively, run /setup-mcp in any project that includes this repo and Claude will detect your OS, collect your wallet addresses, and write the config for you.

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

Most tools quote a fixed USDC price and settle exact on Solana mainnet (prices below come straight from each tool's source); forge_free is free — no payment, no wallet, no API key. 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 VAST-AI UniRig. Takes a `glb_url` (e.g. `mesh_forge`'s output), returns the `riggedGlbUrl` and a three.ws pose-studio link.
`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.
`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 recent pump.fun comments (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.
`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.

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.
`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

Required

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`.

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
`MCP_POSE_PREVIEW_BASE`	`https://three.ws/pose`	Base URL for `get_pose_seed` preview links
`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

Claude Code slash commands

This repo ships three slash commands in .claude/commands/ that work in any project that references this repo:

Command	What it does
`/setup-mcp`	Detects your OS, collects wallet addresses, and writes the MCP config to the right file
`/scaffold-agent`	Scaffolds a new three.ws agent in the current project with MCP client wiring
`/use-tools [tool_name]`	Produces a complete, runnable code example for a specific paid tool

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

Payment flow

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

Client sends a tools/call request (no payment yet).
Server returns PaymentRequired (v2 MCP transport spec) with the USDC amount and payment address.
A payment-aware client (or wrapMCPClientWithPayment) signs and submits the on-chain payment.
Client retries the tools/call with _meta["x402/payment"] attached.
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.

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

README.md

@three-ws/mcp-server

Quickstart (30 seconds)

Claude Code

Claude Desktop

Tools

3D generation

Solana & markets

Agents & identity

Installation

Environment variables

Required

Optional

Claude Code slash commands

Programmatic client

Cursor

Run from source

Payment flow

Reliability & failover

Architecture

Requirements

Related

Links

Uh oh!

FilesExpand file tree

mcp-server

Directory actions

More options

Directory actions

More options

Latest commit

History

mcp-server

Folders and files

parent directory

README.md

@three-ws/mcp-server

Quickstart (30 seconds)

Claude Code

Claude Desktop

Tools

3D generation

Solana & markets

Agents & identity

Installation

Environment variables

Required

Optional

Claude Code slash commands

Programmatic client

Cursor

Run from source

Payment flow

Reliability & failover

Architecture

Requirements

Related

Links