@three-ws/metaplex-agent-mcp

Despliega agentes de IA en cadena en el Registro de Agentes de Metaplex en Solana, desde cualquier cliente MCP.

Un flujo acuña un activo Metaplex Core y registra su identidad de agente EIP-8004 (una única transacción atómica cuando cabe en el límite de 1232 bytes de Solana; de lo contrario, creación y registro en secuencia, exactamente como aterrizó el Genesis 333), de modo que el agente aparece en metaplex.com/agents con su propia billetera integrada, superficie de reputación y páginas de explorador. La salida predeterminada reproduce la forma exacta de las acuñaciones del three.ws Genesis 333, verificadas byte a byte contra los activos en vivo:

• metadatos del activo como URI data:application/json;base64 autocontenida (name, image, animation_url GLB)

• plugin de regalías (5% para el propietario), VerifiedCreators (la billetera firmante), ImmutableMetadata

• plugin AgentIdentity que lleva el documento eip-8004#registration-v1 (model.uri, active, x402Support, registrations, supportedTrust)

Dos vías de firma, ambas de autocustodia:

• Agentes firman con su propio par de claves (SOLANA_SECRET_KEY): mint_onchain_agent.

• Personas firman con Phantom, Solflare, Backpack, Ledger o cualquier billetera de Solana: prepare_agent_mint construye la transacción, la billetera la firma, send_signed_transaction la transmite. Ninguna clave toca el servidor.

Nada está simulado: programas reales de Metaplex, Solana real y soporte de devnet para ensayo gratuito de extremo a extremo.

Instalación

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

Related MCP server: AgentWallet MCP Server

Configuración

Claude Code:

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

Cursor / cualquier cliente 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 es opcional: todas las herramientas de lectura y todo el flujo de Phantom/Solflare funcionan sin ella.

Inicio rápido

Ensaya en devnet gratis y luego pasa a 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" }

La acuñación cuesta ~0.007 SOL en mainnet (renta de Core + renta de PDA de identidad + comisiones).

Herramientas

Personalización

Cada campo que toca la acuñación es un parámetro: propietario, colección, puntos base de regalías y divisiones, creador verificado, metadatos inmutables, Atributos en cadena, delegados permanentes de congelación/transferencia/quema, AddBlocker, atributos de metadatos fuera de cadena, external_url, servicios, modelos de confianza, entradas de registro y anulaciones completas de metadata_uri / registration_uri para documentos que alojas tú mismo. Los valores predeterminados son los del Genesis 333, por lo que llamar solo con name, description, image y model_url produce un activo indistinguible en forma de los originales.

Seguridad

• mint_onchain_agent y register_agent_identity transmiten solo con confirm: true (establece REQUIRE_CONFIRM=false para optar por no participar); las vistas previas no cuestan nada.

• Las claves siguen siendo tuyas: SOLANA_SECRET_KEY o un secret por llamada, nunca una billetera de custodia. La vía de billetera no necesita ninguna clave.

• Los saldos se verifican antes de gastar, los endpoints RPC deben ser HTTPS y devnet es un objetivo de primera clase para el ensayo.

Variables de entorno

Uso como biblioteca

Los constructores se exportan para incrustación directa (aplicaciones web, 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 });

Los constructores de registro y metadatos también se pueden importar por separado (sin dependencias, seguros para navegador) desde @three-ws/metaplex-agent-mcp/lib/registration, y los constructores de transacciones desde @three-ws/metaplex-agent-mcp/lib/mint. La página /deploy-onchain de three.ws se ejecuta exactamente con estos.

Requisitos

• Node 20+

• SOL en la red de destino para acuñar (~0.007 SOL por agente en mainnet; devnet es gratis mediante faucet)

Enlaces

• three.ws: https://three.ws

• Feed de despliegues en vivo: https://three.ws/deployments

• Registro de Agentes de Metaplex: https://www.metaplex.com/agents

• Documentación de Metaplex: https://www.metaplex.com/docs/agents

• Código fuente: https://github.com/nirholas/three.ws/tree/main/packages/metaplex-agent-mcp

Acerca de este repositorio

Este es el hogar independiente de @three-ws/metaplex-agent-mcp. El desarrollo ocurre en el monorepo de three.ws y los lanzamientos se reflejan aquí, por lo que este repositorio siempre coincide con lo publicado en npm y en el registro oficial de MCP (io.github.nirholas/metaplex-agent). Las incidencias y PRs son bienvenidos en cualquiera de los dos lugares.