@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