@three-ws/copy-mcp

Drive your three.ws copy-trading from any AI agent — follow leaders, tune sizing & guard rules, work the copy-intent inbox, and track fees owed. Headless, non-custodial.

A Model Context Protocol server that turns the three.ws copy-trading control surface — follow/unfollow leaders, tune guard rules, read your copy-intent inbox, and see fees owed — into agent-drivable tools over stdio. Everything the website's copy dashboard does, headless.

Non-custodial by design. three.ws never signs a transaction or holds your funds. When a leader you follow trades, the engine produces a sized, guard-checked copy INTENT that you (or your agent) act on from your own wallet. Every order is clamped to your per-trade cap and your remaining daily budget, so a runaway leader can never drain you. Performance fees settle in $THREE.

Install

npm install @three-ws/copy-mcp

Or run with npx (no install):

npx @three-ws/copy-mcp

Quick start

Copy trading is account-scoped, so set THREE_WS_API_KEY to a three.ws API key (sk_live_… / sk_test_…) or OAuth access token. Mint one at three.ws/dashboard/developers.

Claude Code, one line:

claude mcp add copy --env THREE_WS_API_KEY=sk_live_xxx -- npx -y @three-ws/copy-mcp

Claude Desktop / Cursor (claude_desktop_config.json or mcp.json):

{
	"mcpServers": {
		"copy": {
			"command": "npx",
			"args": ["-y", "@three-ws/copy-mcp"],
			"env": { "THREE_WS_API_KEY": "sk_live_xxx" }
		}
	}
}

Inspect the surface with the MCP Inspector:

THREE_WS_API_KEY=sk_live_xxx npx -y @modelcontextprotocol/inspector npx @three-ws/copy-mcp

Discovery (which leaders to follow) lives in @three-ws/intel-mcp → copy_smart_wallets. This server manages the follows you commit to.

Tools

All reads return live data (counts, intents, and accruals move between calls), so none are idempotent.

Input parameters

list_subscriptions — none.

create_subscription — leader_agent_id (required, UUID), copier_wallet (required, base58), network (mainnet | devnet, default mainnet), sizing_rule (fixed | multiplier | pct_balance, default fixed), fixed_sol (required for fixed sizing), multiplier (default 0.1), pct_balance (0–100), per_trade_cap_sol (default 0.5), min_order_sol (default 0.02), daily_budget_sol (default 1), max_open_copies (1–100, default 5), mcap_floor_usd, mcap_ceiling_usd, copy_sells (default true), require_safety_pass (default false), min_oracle_score (0–100), perf_fee_bps (0–3000, default 1000), telegram_chat_id.

update_subscription — id (required, UUID) plus any of: status (active | paused | stopped), and the sizing/guard fields from create_subscription (each optional; pass null to clear mcap_floor_usd / mcap_ceiling_usd / min_oracle_score / telegram_chat_id). Only the fields you pass change. leader_agent_id and network cannot be changed here: they identify the subscription, so re-pointing them means creating a new follow with create_subscription.

cancel_subscription — id (required, UUID).

get_executions — status (pending | acted | dismissed | skipped | expired | all, default pending), limit (1–100, default 50).

record_execution — id (required, UUID), action (acted | dismissed), tx_signature (optional, recorded only when acted).

get_earnings — agent_id (optional UUID — provide for a leader's public aggregate; omit for your own rollup), network (mainnet | devnet, default mainnet).

Example

// create_subscription — follow a leader, 0.05 SOL per copy, capped, safety-gated
> {
    "leader_agent_id": "8f3c…-uuid",
    "copier_wallet": "7Np…YourWallet",
    "sizing_rule": "fixed",
    "fixed_sol": 0.05,
    "per_trade_cap_sol": 0.1,
    "daily_budget_sol": 0.5,
    "mcap_floor_usd": 50000,
    "require_safety_pass": true
  }
{
  "ok": true,
  "subscription": {
    "id": "…",
    "status": "active",
    "network": "mainnet",
    // the create/update responses return the raw subscription row, so leader
    // name/image are null here; list_subscriptions joins the leader profile
    // and also adds pending_count / acted_count per row
    "leader": { "agent_id": "8f3c…", "name": null, "image": null, "wallet": null },
    "copier_wallet": "7Np…YourWallet",
    "sizing": { "rule": "fixed", "fixed_sol": 0.05, "multiplier": 0.1, "pct_balance": 0 },
    "guards": {
      "per_trade_cap_sol": 0.1, "min_order_sol": 0.02, "daily_budget_sol": 0.5,
      "max_open_copies": 5, "mcap_floor_usd": 50000, "mcap_ceiling_usd": null,
      "copy_sells": true, "require_safety_pass": true, "min_oracle_score": null
    },
    "perf_fee_bps": 1000
  }
}

// get_executions — the actionable inbox
> { "status": "pending", "limit": 5 }
{
  "ok": true,
  "status": "pending",
  "count": 1,
  "executions": [
    {
      "id": "…",
      "status": "pending",
      "leader": { "name": "…" },
      "coin": { "mint": "…", "symbol": "…", "name": "…" },
      "direction": "buy",
      "planned_sol": 0.05,
      "expires_at": "…"
    }
  ]
}

// record_execution — you bought it yourself; log the fill
> { "id": "…", "action": "acted", "tx_signature": "5xQ…" }
{ "ok": true, "execution": { "id": "…", "status": "acted", "tx_signature": "5xQ…" } }

Requirements

• Node.js >= 20.
• A three.ws account credential in THREE_WS_API_KEY (all tools except a leader's public aggregate earnings).
• Network access to https://three.ws (or your own THREE_WS_BASE).

Environment variables

Errors

A failed tool call returns an MCP error result (isError: true) whose text is a single JSON object: { "ok": false, "error": "<code>", "message": "…" }, plus status on upstream rejections:

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}