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
Connect any MCP client to three.ws in one command. three-ws signs you in, writes the hosted three.ws MCP servers into every client it finds (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, IBM Bob, Codex, Gemini CLI, Hermes), and verifies each one with a live tools/list. For Grok Bot, whose connectors live in xAI's cloud, it prints the connector fields and checks them live instead.
npx @three-ws/cli setup
Requires Node.js 20.12 or newer.
What you get
The three.ws MCP servers give your assistant 3D generation (text to 3D, image to 3D, rigged avatars), your agents and their wallets, x402 paid services, and Solana token data. The live list is at three.ws/.well-known/mcp.json and every tool is in the catalog.
Using one client that supports remote connectors? three.ws/connect adds three.ws to Claude, Cursor or VS Code in one click, with no terminal.
One command per client
npx @three-ws/cli --claude # also --cursor --codex --vscode --windsurf --gemini --bob --hermes
Signs in, writes the servers, verifies them, and installs the three.ws skill for Claude Code, with no prompts. The config gets a three-ws proxy launcher, never a token: credentials stay in ~/.config/three-ws/credentials.json (mode 600). Running it again changes nothing. Then: claude "launch my agent".
Hosted installers: curl -fsSL https://three.ws/cli/install | sh and curl -fsSL https://three.ws/cli/claude | sh. Every script ships with a .sha256 checksum and an ed25519 .sig; download, read and verify before running: three.ws/docs/cli#verify-before-you-run.
npx @three-ws/cli doctor # bad config, expired sign-in, unreachable server, with the fix for each
npx @three-ws/cli agent status # agents, wallets and balances
npx @three-ws/cli team # your teams; `team status <id>` for one
Clean-container check
tests/container/run.sh packs this package and, for each client, starts a fresh node:22 container, runs the hosted installer against a local stand-in platform, and asserts the config is written without a key, a second run changes nothing, doctor passes and the credential file is mode 600. Needs Docker.
bash packages/three-ws-cli/tests/container/run.sh
Common commands
npx @three-ws/cli setup --clients cursor,vscode --yes # specific clients, no prompts
npx @three-ws/cli setup --project # project-scoped config in this directory
npx @three-ws/cli login --device # sign in over SSH
npx @three-ws/cli signup --agent # an agent signs itself up: Solana key, account, wallet, API key, no email
npx @three-ws/cli link BCDF-GHJK # link this terminal with a code from /dashboard/account
npx @three-ws/cli mcp list --available # every server and its name
npx @three-ws/cli tools --server three-ws-main --enable financial
npx @three-ws/cli status
npx @three-ws/cli create "Nova" --description "A deep-space guide." # an agent with its own Solana wallet
npx @three-ws/cli launch --agent <id> --name Nova --symbol NOVA # prefilled, you sign on three.ws/launch
Pay for x402 and MPP resources from the terminal
three-ws pay <url> fetches a URL, reads its HTTP 402 challenge (x402 v2 PAYMENT-REQUIRED, x402 v1 body, or an MPP Solana charge), picks a Solana option, signs with a key that never leaves your machine, retries once and prints the body. Every payment is checked against a permissions file you own before anything is signed.
three-ws wallet init # key goes to the OS keychain, or an encrypted file behind a passphrase
three-ws wallet address # the public address to fund with USDC
three-ws pay init # writes ~/.config/three-ws/pay-permissions.json (safe defaults)
three-ws pay --dry-run https://three.ws/api/x402/three-intel
three-ws pay https://three.ws/api/x402/three-intel
The dry run signs nothing and prints the decision:
Dry run: nothing was signed or sent.
protocol x402
network solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
amount 0.01 (10000 atomic)
asset EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
payee wwwwwDxFWRn7grgr3Esrsg5C6NvDoDHSA4gaCffccrU
decision allowed by pay-permissions.json
| Flag | Meaning |
|---|---|
--dry-run |
Print protocol, network, exact amount, asset and payee and the permission decision. Signs nothing, spends nothing. |
--max <amount> |
Hard ceiling for this call in whole units (0.05), on top of the permissions file. |
--network <id> |
Only consider offers on this network (solana, devnet, or a CAIP-2 id). |
--method, --data, -H |
Forward a method, body and headers on both the probe and the paid retry. |
--storage keychain|file |
With wallet init: where the key lives. Default tries the keychain, then falls back to the file. |
--json |
Machine-readable output, including errors ({ "error": "<reason>", "exit": <code> }). |
Solana offers are always tried first. EVM offers are skipped.
Key custody
wallet init generates a 32-byte seed and stores it in the OS keychain through @napi-rs/keyring. Where no keychain is reachable (headless Linux, containers) it writes pay-wallet.sealed.json, encrypted with AES-256-GCM under a scrypt-derived key, mode 0600, after prompting for a passphrase of at least 12 characters (or reading THREE_WS_WALLET_PASSPHRASE). The key is never written in plaintext, no command prints it, and wallet init never overwrites an existing wallet. wallet export-public prints the address only.
Permissions file
~/.config/three-ws/pay-permissions.json (override with THREE_WS_PAY_PERMISSIONS). With no file, every payment is refused.
{
"version": 1,
"allowedOrigins": ["https://three.ws"],
"allowedNetworks": ["solana"],
"allowedAssets": ["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"],
"allowedPayees": [],
"maxPerCall": "0.10",
"maxPerDay": "1.00",
"confirmAbove": "0.05"
}
maxPerCall is required. Limits are decimal strings in whole units of the asset, compared exactly. maxPerDay counts a UTC-day ledger of settled payments. Above confirmAbove the CLI asks on the terminal. allowedAssets defaults to mainnet and devnet USDC, and allowedPayees is unrestricted when omitted.
Exit codes
| Code | Reason strings | Meaning |
|---|---|---|
| 0 | Success, or the resource was free | |
| 1 | Other error | |
| 2 | Usage error | |
| 10 | permissions_missing, origin_not_allowed, network_not_allowed, asset_not_allowed, payee_not_allowed, per_call_limit, max_flag_exceeded, daily_limit |
Refused by the permissions file |
| 11 | confirm_required, declined_by_user |
Above confirmAbove and not confirmed |
| 12 | no_payable_option, unsupported_intent, challenge_expired |
The server offered nothing payable here |
| 13 | payment_rejected |
The server rejected the signed payment |
| 14 | wallet_missing, wallet_locked |
No usable wallet |
MCP server
three-ws pay mcp is a stdio MCP server with pay_quote (read-only) and pay_fetch, under the same permissions. It has no confirmation channel, so it refuses any payment above confirmAbove.
{ "mcpServers": { "three-ws-pay": { "command": "npx", "args": ["@three-ws/cli", "pay", "mcp"] } } }
Automation mode
Every command takes --json and --non-interactive. The CLI is built to be driven by scripts and by other agents.
--json: stdout carries exactly one JSON document and nothing else. Progress, warnings and the human sentence for an error go to stderr. A failure prints{ "error": "<reason>", "message": "...", "exit": <code> }on stdout.--non-interactive(orTHREE_WS_NON_INTERACTIVE=1): never prompts and never opens a browser. Missing input is a usage error (exit 2), a missing credential is an auth error (exit 3), and an external skill install without--yesis refused (exit 4). Authenticate withTHREE_WS_API_KEYor--key.
| Exit | Meaning |
|---|---|
| 0 | Success |
| 1 | Other error (an unknown run, an unexpected server answer) |
| 2 | Usage: unknown flag or command, missing or malformed input |
| 3 | Auth: no credential, expired or revoked key, or forbidden |
| 4 | Refused by a guard: the spend policy, the trade firewall, or an unconfirmed external skill |
| 5 | Payment required (HTTP 402) |
| 6 | Network: host unreachable, RPC failure, rate limit or a 5xx |
three-ws pay keeps its own stable codes 10 to 14 (see above). They are the one exception to this table.
| Command | Output (--json) |
|---|---|
agents list / agents get <id|name> |
Your agents with their Solana address |
runs list --agent <id|name> / runs get <run-id> |
Run history, or one run with steps, tool traces and the receipt chain verdict |
wallet balance [--agent <id|name>] |
SOL and USDC of the local pay wallet (read from Solana RPC) or of an agent wallet |
skill install <slug> --agent <id> |
Alias of skills import |
orders list --agent <id|name> [--network devnet] |
The agent's order-engine orders |
report run <run-id> --out run.html |
One self-contained HTML report, see below |
Run report
three-ws report run <run-id> --out run.html writes a single file with inline CSS and JS and no network access: the goal, outcome, decisions, trades, every tool call with input, output and receipt, the receipt chain head and the head hash of the agent's decision trail. It opens offline from disk and can be attached to a ticket or an audit. The same generator backs the "Download report" button on the run page. Run three-ws report run against a run you own; the decision trail head is fetched best-effort and the report says so when it could not be reached.
Grok Bot
Grok Bot's MCP configuration lives in xAI's cloud, so there is no file to write. setup handles the rest: it picks the Grok connector (https://three.ws/api/mcp-grok), copies the URL to your clipboard when a clipboard tool exists, prints the exact fields for Grok Bot's custom MCP connector, and runs a real tools/list against the public URL to prove it answers from outside.
npx @three-ws/cli setup --client grok-bot # free 3D studio, no account, no key
npx @three-ws/cli setup --client grok-bot --connector-key # also mint a key so Grok Bot can use your agents
npx @three-ws/cli setup --clients cursor,grok-bot --yes # local clients and Grok Bot in one run
Grok Bot (cloud connector, nothing to write locally)
Name three-ws
Transport Streamable HTTP
Server URL https://three.ws/api/mcp-grok
Authentication None
--connector-key signs you in, mints one key with the connector preset (read, generate and edit agents, never spend), stores it in the credential file, and reuses it on later runs. Paste it as a Bot secret. --no-copy skips the clipboard. A localhost origin is flagged, because Grok Bot connects from xAI's cloud. Full walkthrough: three.ws/docs/grok.
Sign-in is a browser OAuth flow by default. --device approves a code from any browser, and --key sk_live_... (or THREE_WS_API_KEY) uses an API key from Dashboard → API. Tools that move funds are off unless you sign in with --financial and enable them.
Grok Bot
Grok Bot keeps its connectors in xAI's cloud, so setup has no file to write for it. It picks the server, gets the credential, prints the fields Grok Bot's custom MCP connector form asks for, copies the server URL to the clipboard, and runs initialize + tools/list against the public URL the way Grok Bot will.
npx three-ws setup --client grok-bot # free 3D studio, no account
npx three-ws setup --client grok-bot --auth install # free, a quota that survives reconnects
npx three-ws setup --client grok-bot --auth key # mints a connector key that can never spend
npx three-ws setup --client grok-bot --auth oauth # Grok Bot signs in itself
Grok Bot three-ws-grok · add it in Grok Bot's Connectors (custom MCP server); nothing is written on this machine
Name three-ws-grok
Transport Streamable HTTP
Server URL https://three.ws/api/mcp-grok
Authentication None
✔ Server URL copied to the clipboard
Live check https://three.ws/api/mcp-grok
✔ public https URL a cloud agent can reach three.ws
✔ initialize + tools/list 15 tools from three-ws-3d-studio-free 1.0.0
--connector-key sk_live_... uses a key you made at Dashboard → API ("For an AI agent") instead of minting one; a key that can spend is refused. --servers <name> connects another server. mcp add and mcp remove do not apply to Grok Bot, since there is no local file. Details: three.ws/docs/cli#grok-bot and the Grok Bot connector reference.
Programmatic use
The package exports its building blocks (server directory, client detection, config writers, OAuth helpers) for tools that want to reuse them. List every hosted server and the name clients store it under:
import { loadDirectory, hostedServers } from 'three-ws';
const origin = 'https://three.ws';
const directory = await loadDirectory(origin);
for (const server of hostedServers(directory, origin)) console.log(server.slug, server.url);
// three-ws-main https://three.ws/api/mcp
// three-ws-studio https://three.ws/api/mcp-studio
// ...
Docs
Full reference, client config paths and troubleshooting: three.ws/docs/cli.
License
Apache-2.0