@three-ws/metaplex-agent-mcp

@three-ws/metaplex-agent-mcp

Deploy AI agents on-chain into the Metaplex Agent Registry on Solana, from any MCP client.

One flow mints a Metaplex Core asset and registers its EIP-8004 agent identity (a single atomic transaction when it fits Solana's 1232-byte limit, create + register in sequence otherwise, exactly how the Genesis 333 landed), so the agent shows up on metaplex.com/agents with its own built-in wallet, reputation surface, and explorer pages. The default output reproduces the exact shape of the three.ws Genesis 333 mints, verified byte-for-byte against the live assets:

• asset metadata as a self-contained data:application/json;base64 URI (name, image, animation_url GLB)
• Royalties plugin (5% to the owner), VerifiedCreators (the signing wallet), ImmutableMetadata
• AgentIdentity plugin carrying the eip-8004#registration-v1 document (model.uri, active, x402Support, registrations, supportedTrust)

Two signing lanes, both self-custodial:

• Agents sign with their own keypair (SOLANA_SECRET_KEY): mint_onchain_agent.
• People sign with Phantom, Solflare, Backpack, Ledger, or any Solana wallet: prepare_agent_mint builds the transaction, the wallet signs it, send_signed_transaction broadcasts it. No key ever touches the server.

A mainnet deploy pays a flat 0.02 SOL fee, in the same transaction as the mint, and that fee funds $THREE buybacks. Hold $THREE and it halves, then disappears; devnet never pays it. Every preview shows the number and its recipient before anything is signed. See $THREE: the deploy fee and the holder waiver.

Nothing is mocked: real Metaplex programs, real Solana, and devnet support for free end-to-end rehearsal.

Install

npm install -g @three-ws/metaplex-agent-mcp
# or run ad hoc
npx -y @three-ws/metaplex-agent-mcp

Setup

Claude Code:

claude mcp add metaplex-agent -e SOLANA_SECRET_KEY=<base58> -- npx -y @three-ws/metaplex-agent-mcp

Cursor / any MCP client (mcp.json):

{
	"mcpServers": {
		"metaplex-agent": {
			"command": "npx",
			"args": ["-y", "@three-ws/metaplex-agent-mcp"],
			"env": { "SOLANA_SECRET_KEY": "<base58 secret key>" }
		}
	}
}

SOLANA_SECRET_KEY is optional: every read tool and the whole Phantom/Solflare flow works without it.

Quick start

Rehearse on devnet for free, then go to mainnet:

1. agent_wallet {}                                → confirm the signer is funded
2. mint_onchain_agent { name: "Astra", description: "…",
     image: "https://…png", model_url: "https://…glb",
     x402_support: true, network: "devnet" }      → preview (nothing broadcast)
3. …same call with confirm: true                  → minted + registered, links returned
4. get_onchain_agent { asset: "<returned asset>", network: "devnet" }

A mainnet deploy costs ~0.027 SOL: ~0.007 in Core rent, identity PDA rent, and network fees, plus a flat 0.02 SOL deploy fee that funds $THREE buybacks. Holding $THREE halves that fee and then waives it, and devnet is free. See $THREE.

Tools

Tool	What it does
mint_onchain_agent	Mint + register, signed by your key (atomic when it fits, auto-split otherwise). confirm:true gates the spend; anything else returns a full preview.
prepare_agent_mint	The same mint, built for an external wallet (wallet param) to sign. Returns txs_base64, already co-signed by the new asset keypair; sign with signTransaction / signAllTransactions.
send_signed_transaction	Broadcast wallet-signed transactions in order, polling each to confirmation and absorbing the create/register propagation race.
register_agent_identity	Enrol an already-minted Core asset in the Agent Registry (idempotent; the signer must be the asset authority).
get_onchain_agent	Read any registered agent: asset, plugins, decoded metadata + registration documents, identity PDA, built-in wallet + balance.
agent_wallet	An asset's built-in wallet (mpl-core Asset Signer PDA), any address, or the configured signer, with live SOL balance.
build_registration	The EIP-8004 registration JSON + data: URI, fully offline.
list_onchain_agents	Latest registrations from the live three.ws /api/deployments feed (Solana by default, all_chains:true for EVM ERC-8004 too).
three_status	Prices your next deploy: fee schedule, a wallet's live $THREE balance and tier, and the public buyback ledger.

$THREE: the deploy fee and the holder waiver

A mainnet deploy carries a flat 0.02 SOL fee. Three things about it matter:

• It rides in the same transaction that creates the asset. A deploy that fails, is rejected, or expires moves no money. There is no separate payment step and nothing to reconcile.
• It is disclosed before anything is signed. Every mint_onchain_agent preview and every prepare_agent_mint response returns deploy_fee_sol and deploy_fee_to, with the tier that produced them.
• It funds $THREE buybacks. The fee is paid to the wallet the three.ws $THREE buyback lane spends from (FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump is the mint), and the public ledger of what that lane has bought is at /api/three-token/stats. Deploys are the only revenue this package has.

Holding $THREE makes it cheaper, then free:

$THREE in the paying wallet	Deploy fee
under 50,000	0.02 SOL
50,000 or more	0.01 SOL
250,000 or more	free

The balance is read live from the chain when the transaction is built. Nothing is staked, escrowed, locked, or spent to earn it: hold the tokens in your own wallet and keep them, and the waiver applies to every agent you deploy. Devnet always pays zero, so a full end-to-end rehearsal stays free.

three_status {}                                  → what your next deploy costs and why
three_status { wallet: "<any base58 address>" }  → price it for someone else's wallet

Self-hosting a fork with different economics is DEPLOY_FEE_SOL, DEPLOY_FEE_WALLET, and DEPLOY_FEE_ENABLED.

Customization

Every field the mint touches is a parameter: owner, collection, royalty basis points and splits, verified creator, immutable metadata, on-chain Attributes, permanent freeze/transfer/burn delegates, AddBlocker, off-chain metadata attributes, external_url, services, trust models, registration entries, and full metadata_uri / registration_uri overrides for documents you host yourself. The defaults are the Genesis 333 values, so calling with just name, description, image, and model_url produces an asset indistinguishable in shape from the originals.

Safety

• mint_onchain_agent and register_agent_identity broadcast only with confirm: true (set REQUIRE_CONFIRM=false to opt out); previews cost nothing.
• Keys stay yours: SOLANA_SECRET_KEY or a per-call secret, never a custodial wallet. The wallet lane needs no key at all.
• Balances are checked before spending, RPC endpoints must be HTTPS, and devnet is a first-class target for rehearsal.

Environment variables

Variable	Default	Meaning
SOLANA_SECRET_KEY	unset	Base58 secret key or JSON byte array for the minting wallet.
SOLANA_RPC_URL	public endpoint	HTTPS RPC. Bring your own for production traffic.
METAPLEX_AGENT_NETWORK	mainnet	Default cluster (mainnet or devnet); every tool takes a per-call network too.
REQUIRE_CONFIRM	true	Gate spends behind confirm: true.
THREE_WS_BASE	https://three.ws	Host for the deployments feed and the $THREE ledger.
DEPLOY_FEE_SOL	0.02	Mainnet deploy fee, in SOL.
DEPLOY_FEE_WALLET	three.ws buyback wallet	Where the deploy fee is paid.
DEPLOY_FEE_ENABLED	true	Set false to build a fork that charges nothing.
THREE_HALF_PRICE_AT / THREE_FREE_AT	50000 / 250000	$THREE balances that halve, then waive, the fee.
THREE_MINT	$THREE mint	Only to track an updated canonical contract.

Library use

The builders are exported for direct embedding (web apps, scripts):

import { buildAgentMint, sendAgentMint, buildUmi, toBase58Signature } from '@three-ws/metaplex-agent-mcp/lib';

const umi = buildUmi({ network: 'devnet', secret: process.env.SOLANA_SECRET_KEY });
const mint = buildAgentMint(umi, {
	network: 'devnet',
	creator: umi.identity.publicKey.toString(),
	name: 'Astra',
	description: 'An autonomous 3D agent',
	image: 'https://example.com/astra.png',
	modelUrl: 'https://example.com/astra.glb',
	x402Support: true,
});
const { signatures, atomic } = await sendAgentMint(umi, mint, { toBase58Signature });

The registration and metadata builders are also importable on their own (dependency-free, browser-safe) from @three-ws/metaplex-agent-mcp/lib/registration, and the transaction builders from @three-ws/metaplex-agent-mcp/lib/mint. The three.ws /deploy-onchain page runs on exactly these.

Requirements

• Node 20+
• SOL on the target network for minting (~0.027 SOL per agent on mainnet, or ~0.007 with the holder waiver; devnet is free via faucet)

Links

• three.ws: https://three.ws
• $THREE: https://three.ws/three
• Live deployments feed: https://three.ws/deployments
• Metaplex Agent Registry: https://www.metaplex.com/agents
• Metaplex docs: https://www.metaplex.com/docs/agents
• Source: https://github.com/nirholas/three.ws/tree/main/packages/metaplex-agent-mcp