Skip to content
Conduit

mcp server

metaplex-agent-mcp

Deploy AI agents on-chain into the Metaplex Agent Registry on Solana: one atomic transaction mints a Metaplex Core asset (data: URI metadata, verified creator, royalties, immutable metadata) and regis

nirholas/metaplex-agent-mcpcommunitylistedunreviewed
Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

  • Node.js 20 or newer
~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "metaplex-agent-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@three-ws/metaplex-agent-mcp"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 25, 2026

@three-ws/metaplex-agent-mcp

GitHub stars License Last commit PRs welcome AI agent friendly

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

ToolWhat it does
mint_onchain_agentMint + 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_mintThe 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_transactionBroadcast wallet-signed transactions in order, polling each to confirmation and absorbing the create/register propagation race.
register_agent_identityEnrol an already-minted Core asset in the Agent Registry (idempotent; the signer must be the asset authority).
get_onchain_agentRead any registered agent: asset, plugins, decoded metadata + registration documents, identity PDA, built-in wallet + balance.
agent_walletAn asset's built-in wallet (mpl-core Asset Signer PDA), any address, or the configured signer, with live SOL balance.
build_registrationThe EIP-8004 registration JSON + data: URI, fully offline.
list_onchain_agentsLatest registrations from the live three.ws /api/deployments feed (Solana by default, all_chains:true for EVM ERC-8004 too).
three_statusPrices 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 walletDeploy fee
under 50,0000.02 SOL
50,000 or more0.01 SOL
250,000 or morefree

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

VariableDefaultMeaning
SOLANA_SECRET_KEYunsetBase58 secret key or JSON byte array for the minting wallet.
SOLANA_RPC_URLpublic endpointHTTPS RPC. Bring your own for production traffic.
METAPLEX_AGENT_NETWORKmainnetDefault cluster (mainnet or devnet); every tool takes a per-call network too.
REQUIRE_CONFIRMtrueGate spends behind confirm: true.
THREE_WS_BASEhttps://three.wsHost for the deployments feed and the $THREE ledger.
DEPLOY_FEE_SOL0.02Mainnet deploy fee, in SOL.
DEPLOY_FEE_WALLETthree.ws buyback walletWhere the deploy fee is paid.
DEPLOY_FEE_ENABLEDtrueSet false to build a fork that charges nothing.
THREE_HALF_PRICE_AT / THREE_FREE_AT50000 / 250000$THREE balances that halve, then waive, the fee.
THREE_MINT$THREE mintOnly 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. 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

Support the project

If metaplex-agent-mcp saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.

Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit

Built for AI agents too

Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/metaplex-agent-mcp and it has the context it needs.

More from the same author

Contributors

Contributors

Star history

Star History Chart

Part of three.ws

three.ws is a platform for 3D AI agents with Solana wallets: avatars, a skill marketplace, x402 payments and more than seventy MCP servers. @three-ws/metaplex-agent-mcp is one package from it.

↑↓ navigate openesc close