Metaplex Agent Registry

@three-ws/metaplex-agent-mcp

任意の MCP クライアントから、Solana 上の Metaplex Agent Registry に AI エージェントをオンチェーンでデプロイします。

1 つのフローで Metaplex Core アセットをミントし、その EIP-8004 エージェント IDを登録します（Solana の 1232 バイト制限内に収まる場合は単一のアトミックトランザクションで実行し、収まらない場合は作成、登録の順に実行します。これは Genesis 333 が実際にオンチェーンに記録された方法と同じです）。これにより、そのエージェントは独自の組み込みウォレット、レピュテーション画面、エクスプローラーページとともに metaplex.com/agents に表示されます。デフォルトの出力は、ライブアセットとバイト単位で照合済みの three.ws Genesis 333 ミントの正確な形式を再現します。

• 自己完結型の data:application/json;base64 URI としてのアセットメタデータ（name、image、animation_url GLB）
• ロイヤリティプラグイン（所有者に 5%）、VerifiedCreators（署名ウォレット）、ImmutableMetadata
• eip-8004#registration-v1 ドキュメント（model.uri、active、x402Support、registrations、supportedTrust）を含む AgentIdentity プラグイン

どちらも自己管理型の、2 つの署名方法に対応しています。

• エージェントは自身のキーペア（SOLANA_SECRET_KEY）で署名します：mint_onchain_agent。
• ユーザーは Phantom、Solflare、Backpack、Ledger、または任意の Solana ウォレットで署名します：prepare_agent_mint でトランザクションを作成し、ウォレットで署名してから、send_signed_transaction でブロードキャストします。秘密鍵がサーバーに渡ることはありません。

mainnet へのデプロイでは、ミントと同じトランザクション内で定額の 0.02 SOL の手数料が支払われ、この手数料は $THREE の買い戻しに充てられます。$THREE を保有すると手数料は半額になり、その後免除されます。devnet では手数料はかかりません。プレビューには、署名前に必ず手数料の金額と受取先が表示されます。詳しくは $THREE：デプロイ手数料と保有者向け免除 をご覧ください。

モックはありません。実際の Metaplex プログラム、実際の Solana、そして無料のエンドツーエンドのリハーサルに対応した devnet サポートを提供します。

インストール

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

セットアップ

Claude Code：

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

Cursor／任意の MCP クライアント（mcp.json）：

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

SOLANA_SECRET_KEY は任意です。すべての読み取りツールと Phantom／Solflare のフロー全体は、これがなくても動作します。

クイックスタート

まず無料で devnet 上でリハーサルし、その後 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" }

mainnet へのデプロイには約 0.027 SOL かかります。Core のレンタル料、アイデンティティ PDA のレンタル料、ネットワーク手数料として約 0.007 SOL、さらに $THREE の買い戻しに充てられる定額 0.02 SOL のデプロイ手数料が必要です。$THREE を保有すると手数料は半額になり、その後免除されます。devnet は無料です。詳しくは $THREE をご覧ください。

ツール

ツール	機能
mint_onchain_agent	ミントして登録します。お使いのキーで署名します（収まる場合はアトミックに実行し、それ以外は自動で分割します）。confirm:true で支払いを確定します。それ以外の場合は完全なプレビューを返します。
prepare_agent_mint	外部ウォレット（wallet パラメーター）で署名するために、同じミントのトランザクションを作成します。新しいアセットのキーペアでの共同署名が済んだ txs_base64 を返します。signTransaction／signAllTransactions で署名してください。
send_signed_transaction	ウォレット署名済みのトランザクションを順にブロードキャストし、それぞれの確定までポーリングして、作成／登録間の伝播競合を吸収します。
register_agent_identity	ミント済みの Core アセットを Agent Registry に登録します（冪等です。署名者はアセットの権限者である必要があります）。
get_onchain_agent	登録済みエージェントを読み取ります：アセット、プラグイン、デコード済みメタデータと登録ドキュメント、アイデンティティ PDA、組み込みウォレットと残高。
agent_wallet	アセットの組み込みウォレット（mpl-core Asset Signer PDA）、任意のアドレス、または設定済みの署名者と、そのリアルタイム SOL 残高を取得します。
build_registration	EIP-8004 登録 JSON と data: URI を完全オフラインで作成します。
list_onchain_agents	ライブの three.ws /api/deployments フィードから最新の登録を取得します（デフォルトは Solana、all_chains:true で EVM の ERC-8004 も対象になります）。
three_status	次回のデプロイ費用を算出します：手数料の体系、ウォレットのリアルタイム $THREE 残高とティア、公開買い戻し台帳。

$THREE：デプロイ料金と保有者向け免除

メインネットへのデプロイには、一律 0.02 SOL の料金がかかります。重要な点は次の3つです。

• アセットを作成するトランザクションに含まれます。 デプロイが失敗、拒否、または期限切れになった場合、資金は移動しません。別途支払い手順はなく、照合も不要です。
• 署名する前に開示されます。 すべての mint_onchain_agent のプレビューと prepare_agent_mint のレスポンスで、料金を決定したティアとともに deploy_fee_sol と deploy_fee_to が返されます。
• $THREE の買い戻しに充てられます。 料金は、three.ws の $THREE 買い戻し用に資金を支出するウォレットに支払われます （FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump がミントです）。この買い戻しの公開台帳は /api/three-token/stats にあります。デプロイがこのパッケージ唯一の収益源です。

$THREE を保有すると料金が安くなり、やがて無料になります。

支払いウォレット内の $THREE	デプロイ料金
50,000 未満	0.02 SOL
50,000 以上	0.01 SOL
250,000 以上	無料

残高はトランザクションの構築時にチェーンからリアルタイムで読み取られます。特典を得るためにステーキング、エスクロー、ロック、または消費を行う必要はありません。トークンをご自身のウォレットで保有し続ければ、デプロイするすべてのエージェントに免除が適用されます。Devnet では常に無料なので、エンドツーエンドのリハーサルをすべて無料で行えます。

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

異なる料金体系でフォークをセルフホストする場合は、DEPLOY_FEE_SOL、DEPLOY_FEE_WALLET、DEPLOY_FEE_ENABLED を設定します。

カスタマイズ

ミントで扱うすべてのフィールドをパラメーターとして指定できます。所有者、コレクション、ロイヤリティのベーシスポイントと分配、検証済みクリエイター、不変メタデータ、オンチェーン属性、恒久的な凍結／転送／焼却デリゲート、AddBlocker、オフチェーンメタデータ属性、external_url、サービス、信頼モデル、登録エントリー、さらに自分でホストするドキュメント用の完全な metadata_uri／registration_uri 上書きが含まれます。デフォルトは Genesis 333 の値なので、name、description、image、model_url だけを指定して呼び出すと、元のものと形式上見分けのつかないアセットが生成されます。

安全性

• mint_onchain_agent と register_agent_identity は、confirm: true の場合にのみブロードキャストします（オプトアウトするには REQUIRE_CONFIRM=false を設定します）。プレビューに費用はかかりません。
• キーはご自身で管理します。使用するのは SOLANA_SECRET_KEY または呼び出しごとの secret であり、カストディアルウォレットは使用しません。ウォレットレーンにキーは不要です。
• 支出前に残高を確認し、RPC エンドポイントには HTTPS が必須です。また、リハーサル用の対象として devnet を正式にサポートしています。

環境変数

変数	デフォルト	意味
SOLANA_SECRET_KEY	未設定	ミント用ウォレットの Base58 秘密鍵または JSON バイト配列です。
SOLANA_RPC_URL	パブリックエンドポイント	HTTPS RPC です。本番トラフィックでは独自のエンドポイントを使用してください。
METAPLEX_AGENT_NETWORK	mainnet	デフォルトのクラスター（mainnet または devnet）です。すべてのツールで呼び出しごとに network も指定できます。
REQUIRE_CONFIRM	true	支出には confirm: true が必要です。
THREE_WS_BASE	https://three.ws	デプロイフィードと $THREE 台帳のホストです。
DEPLOY_FEE_SOL	0.02	メインネットのデプロイ料金（SOL 単位）です。
DEPLOY_FEE_WALLET	three.ws 買い戻しウォレット	デプロイ料金の支払い先です。
DEPLOY_FEE_ENABLED	true	料金を請求しないフォークを構築するには false に設定します。
THREE_HALF_PRICE_AT / THREE_FREE_AT	50000 / 250000	料金が半額になり、その後免除される $THREE 残高です。
THREE_MINT	$THREE ミント	正式なコントラクトが更新された場合に追跡するためだけに使用します。

ライブラリの使用

ビルダーは直接埋め込めるようにエクスポートされています（ウェブアプリ、スクリプト向け）。

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 });

登録ビルダーとメタデータビルダーは、@three-ws/metaplex-agent-mcp/lib/registration から単独でインポートすることもできます（依存関係がなく、ブラウザーで安全に使用できます）。トランザクションビルダーは @three-ws/metaplex-agent-mcp/lib/mint からインポートできます。three.ws の /deploy-onchain ページは、これらとまったく同じものを使用しています。atomic が false の場合でも、combinedBuilder にはミント全体が保持されます。Solana トランザクション v1（4,096 バイトの上限）としてコンパイルすると、作成と登録が1つのアトミックなトランザクションにまとめられます。/deploy-onchain は、v1 署名に対応しているウォレットであれば、どのウォレットでもこの方式を使用します。

要件

• Node 20+
• ミントするには対象ネットワーク上の SOL が必要です（メインネットではエージェント1つあたり約0.027 SOL、ホルダー免除が適用される場合は約0.007 SOL。devnet はフォーセット経由で無料です）。

リンク

• three.ws：https://three.ws
• $THREE：https://three.ws/three
• デプロイのライブフィード：https://three.ws/deployments
• Metaplex Agent Registry：https://www.metaplex.com/agents
• Metaplex のドキュメント：https://www.metaplex.com/docs/agents
• ソース：https://github.com/nirholas/three.ws/tree/main/packages/metaplex-agent-mcp