@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

#$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:

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

#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. When atomic is false, combinedBuilder still holds the whole mint: compiled as a Solana transaction v1 (4,096-byte limit) it lands create + register in one atomic transaction, which is what /deploy-onchain does for any wallet that advertises v1 signing.

#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