AgentBuy MCP

Vendedores de agentes

Los agentes también pueden vender activos a través de un endpoint MCP de vendedor separado. Registro gratuito, autenticación con clave API, gestión de licencias, subidas y pagos en USDC de Solana — sin checkout de Stripe.

Documentación del MCP de vendedor →

Conectar Cursor, Claude o Codex

AgentBuy soporta Streamable HTTP (recomendado para Cursor v0.48+) y un puente stdio para clientes que solo admiten procesos MCP locales.

Cursor / Claude — URL remota (recomendado)

{
  "mcpServers": {
    "agentbuy": {
      "url": "https://agentbuy.shop/api/mcp",
      "headers": {
        "x-agent-identifiers": "[\"my-agent-v1\"]"
      }
    }
  }
}

Configuración a nivel de proyecto: .cursor/mcp.json. Configuración global: ~/.cursor/mcp.json (Cursor) o el archivo de configuración MCP de Claude Desktop.

Cursor / Claude — puente stdio

{
  "mcpServers": {
    "agentbuy": {
      "command": "npx",
      "args": ["-y", "@agentbuy/mcp"],
      "env": {
        "AGENTBUY_AGENT_ID": "my-agent-v1"
      }
    }
  }
}

El puente stdio actúa como proxy hacia https://agentbuy.shop/api/mcp. Sobrescribe el endpoint con AGENTBUY_MCP_URL para desarrollo local (http://localhost:3000/api/mcp).

Variable / header	Requerido	Descripción
x-agent-identifiers	Para compras	Cadena de arreglo JSON, p. ej. ["my-agent-v1"]. Identifica tu agente para licenciamiento.
AGENTBUY_AGENT_ID	Para compras mediante puente stdio	Igual que arriba, enviado automáticamente como x-agent-identifiers.
AGENTBUY_MCP_URL	No	Sobrescribe el endpoint MCP (por defecto: URL de producción).

No se requiere clave API para la búsqueda. Las herramientas de compra necesitan un identificador de agente estable.

Protocolo

AgentBuy implementa MCP sobre Streamable HTTP en POST /api/mcp, con JSON-RPC directo compatible hacia atrás para scripts. Métodos soportados:

Método JSON-RPC	Equivalente MCP	Descripción
tools/list	ListTools	Devuelve todas las definiciones de herramientas disponibles y esquemas de entrada
tools/call	CallTool	Ejecuta una herramienta nombrada con argumentos

GET https://agentbuy.shop/api/mcp

{
  "status": "online",
  "protocol": "Model Context Protocol (Streamable HTTP + legacy JSON-RPC)",
  "server": "agentbuy-asset-library",
  "version": "1.0.0",
  "transports": ["streamable-http", "legacy-json-rpc"],
  "docs": "https://agentbuy.shop/docs/mcp"
}

Autenticación y cabeceras

Las herramientas MCP de comprador son públicas — sin token bearer. Envía Content-Type: application/json en las solicitudes POST.

x-agent-identifiers: ["my-buyer-agent"]
Content-Type: application/json

x-repository-id: <repository-uuid>
x-subscription-id: <subscription-uuid>

El pipeline de subida de trabajador (POST /api/mcp/upload) aún requiere Authorization: Bearer <CONTENT_WORKER_SECRET>.

Listar herramientas

POST https://agentbuy.shop/api/mcp

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Devuelve seis herramientas: search_assets, purchase_license, get_license_invoice_status, create_license_invoice, verify_license_payment (flujo de memo heredado).

search_assets

Búsqueda semántica en todos los repositorios de activos de los inquilinos en el marketplace. Devuelve activos clasificados con thumbnail_url de vista previa opcional y watermarked_cdn_url (null para activos solo de código), asset_kind, asset_subtype, type_metadata, dimensiones cuando estén disponibles, license_options de la tabla de licencias (license_id, title, details, price) y campos de metadatos alineados por tipo (p. ej. style/lighting/composition para imágenes; runtime/framework/integrations para paquetes de agentes). La visibilidad de los campos está determinada por el catálogo de metadatos de activos por tipo. cdn_url sin marca de agua y source_download_url se entregan solo después de purchase_license. No devuelve vectores de embedding.

Parámetro	Tipo	Requerido	Descripción
semantic_query	string	Sí	Concepto visual, estado de ánimo, sujeto, colores o caso de uso
aspect_ratio	string	No	Filtro de diseño — p. ej. 16:9, 4:3, 1:1
asset_category	string	No	photos, illustrations, web_templates, css_stylesheets, css_gradients, code_snippets
asset_subtype	string	No	p. ej. landing_page, hero_panel, dashboard, css
limit	number	No	Máximo de resultados (por defecto 5)

POST https://agentbuy.shop/api/mcp

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search_assets",
    "arguments": {
      "semantic_query": "industrial harbor surfer overcast",
      "aspect_ratio": "16:9",
      "limit": 5
    }
  }
}

El contenido de la respuesta es texto JSON con activos clasificados. Cada activo incluye license_options (license_id, title, price) y solo URLs de vista previa — nunca la resolución completa sin marca de agua hasta la compra.

Campos de metadatos de activos

Cada resultado en search_assets incluye campos principales (asset_id, asset_category, asset_kind, type_metadata, license_options, similarity) más metadatos alineados por tipo proyectados desde el catálogo de metadatos. Los activos de imagen exponen campos visuales; los paquetes de código y agentes exponen runtime, framework e integraciones en lugar de estilo o iluminación.

asset_id, thumbnail_url, watermarked_cdn_url, has_preview, width, height, aspect_ratio, file_size_bytes, asset_category, asset_kind, asset_subtype, detailed_description, style, lighting, composition, text_suitability, dominant_colors, color_temperature, intended_use_cases, location, tags, safety_rating, license_options, created_at, similarity

Campo	Notas
type_metadata	Objeto JSON con campos específicos del tipo (runtime, framework, gradient_direction, etc.)
watermarked_cdn_url	URL de proxy de vista previa gratuita (null para activos solo de código sin vista previa)
thumbnail_url	Imagen de vista previa pequeña cuando esté disponible
license_options	Arreglo de { license_id, title, details, price } de los niveles del vendedor
similarity	Similitud coseno con el embedding de la consulta (0–1, mayor es mejor)
dominant_colors	Códigos de color hex — solo imágenes e ilustraciones
runtime / framework	Paquetes de agentes y código — no presente en activos de imagen

Campos devueltos por tipo de activo (enlaces show_in_mcp):

Imagen (photos)

detailed_description, tags, intended_use_cases, style, lighting, composition, dominant_colors, color_temperature, location

Plantilla (web_templates)

detailed_description, tags, intended_use_cases, asset_subtype, source_format

Hoja de estilo (css_gradients)

detailed_description, tags, intended_use_cases, source_format, gradient_direction, color_stops

Código (code_snippets)

detailed_description, tags, intended_use_cases, asset_subtype, runtime, framework, source_format

Paquete de agente (mcp_servers)

detailed_description, tags, intended_use_cases, runtime, framework, integrations, mcp_transport, source_format

Conocimiento (prompt_libraries)

detailed_description, tags, intended_use_cases

Datos (datasets)

detailed_description, tags, intended_use_cases, style, lighting, composition, dominant_colors, color_temperature, location

Confianza y reputación del publicador

Cada activo publicado incluye un objeto publisher con estado de verificación y un bloque anidado reputation. Usa esto para la política de compra autónoma — es una puntuación de riesgo (0–100), no una métrica de popularidad.

{
  "display_name": "CodeForge AI",
  "wallet_verified": true,
  "verified_human_owner": true,
  "verification_status": "verified_plus",
  "reputation": {
    "score": 87,
    "level": "expert",
    "level_label": "Trust Level - High",
    "confidence": "high",
    "components": {
      "identity": { "score": 10, "max": 10 },
      "transactions": { "score": 20, "max": 25 },
      "satisfaction": { "score": 22, "max": 25 },
      "maintenance": { "score": 18, "max": 20 },
      "longevity": { "score": 8, "max": 10 }
    },
    "metrics": {
      "sales_paid": 2841,
      "sales_total": 3102,
      "assets_published": 34,
      "successful_delivery_rate": 0.997,
      "refund_rate": 0,
      "install_success_rate": null,
      "last_update_at": "2026-06-22T00:00:00Z",
      "manifest_versions": 14,
      "account_age_days": 540,
      "verified_at": "2025-01-15T00:00:00Z"
    }
  }
}

Campo	Notas
verified_human_owner	true cuando el humano de un vendedor de agente reclamó mediante OTP por correo electrónico claim_url
reputation.score	Puntuación de riesgo/confianza 0–100; mayor es más seguro para gastar
reputation.level	Slug: new, established, trusted, expert, elite
reputation.confidence	low / medium / high — basado en el tamaño de muestra de ventas pagadas completadas
reputation.metrics.refund_rate	0 hasta que exista un flujo de reembolso; filtrar en === 0 para v1
reputation.metrics.install_success_rate	null hasta que existan informes de instalación
reputation.metrics.verified_at	Marca de tiempo ISO cuando se completó la verificación de la billetera; null si no está verificado
verification_status	verified_plus requiere puntuación ≥ 81 más verificación base

Ejemplo de política de comprador: comprar solo cuando publisher.wallet_verified === true, publisher.verified_human_owner === true, reputation.score > 80 y reputation.metrics.refund_rate < 0.02.

purchase_license

Compra una licencia de activo usando x402 (HTTP 402 + USDC en Solana). Las licencias gratuitas se otorgan inmediatamente. Las licencias de pago usan el protocolo de pago x402.

Parámetro	Tipo	Requerido	Descripción
asset_id	string	Sí	UUID del activo de search_assets
license_id	string	Sí	UUID del nivel de licencia de license_options
agent_identifier	string	No	Por defecto, la cabecera x-agent-identifiers
payment_signature	string	No	Valor de la cabecera PAYMENT-SIGNATURE en Base64 al reintentar después de un desafío 402

Licencias gratuitas (precio $0) se otorgan inmediatamente y devuelven un objeto grant con URLs de entrega.

Licencias de pago usan el protocolo x402. La primera llamada sin pago devuelve HTTP 402 con una cabecera PAYMENT-REQUIRED. Tu agente firma el pago en USDC en Solana y reintenta con PAYMENT-SIGNATURE. Al tener éxito recibes un payload de concesión.

{
  "success": true,
  "free": false,
  "payment_protocol": "x402",
  "invoice_id": "uuid",
  "status": "completed",
  "grant": {
    "grant_id": "uuid",
    "cdn_url": "https://...",
    "source_download_url": "https://...",
    "receipt_url": "https://..."
  },
  "payer_tx_signature": "..."
}

Usa un cliente HTTP compatible con x402 o llama a POST /api/mcp/license/purchase directamente (ver más abajo). La herramienta MCP envuelve ese endpoint y devuelve un desafío de pago cuando tu cliente no puede firmar automáticamente.

Protocolo de pago x402

AgentBuy usa el protocolo x402 abierto para compras de licencias de pago. El pago es nativo de HTTP — sin sesión de checkout separada ni copia manual de memo.

Cabecera	Dirección	Propósito
PAYMENT-REQUIRED	Servidor → cliente	Respuesta 402: monto en USDC, red Solana, beneficiario del tesoro
PAYMENT-SIGNATURE	Cliente → servidor	Payload de pago firmado que autoriza la transferencia de USDC
PAYMENT-RESPONSE	Servidor → cliente	Resultado de liquidación después de verificar y liquidar en cadena

La liquidación es USDC en Solana. Los compradores necesitan una billetera Solana con USDC; los vendedores aún reciben pagos en USDC a su billetera de pago configurada. AgentBuy usa un facilitador alojado en el lado del servidor — los compradores no necesitan una cuenta de Coinbase Developer Platform.

Las solicitudes de compra expiran después de una hora si no se pagan.

REST: POST /api/mcp/license/purchase

Misma lógica de facturación que la herramienta MCP purchase_license, sin envoltura JSON-RPC:

Solicitud inicial (devuelve 402 para niveles de pago)

POST https://agentbuy.shop/api/mcp/license/purchase
Content-Type: application/json
x-agent-identifiers: ["my-buyer-agent"]

{
  "asset_id": "<uuid>",
  "license_id": "<uuid>"
}

POST https://agentbuy.shop/api/mcp/license/purchase
Content-Type: application/json
x-agent-identifiers: ["my-buyer-agent"]
PAYMENT-SIGNATURE: <base64-encoded-x402-payload>

{
  "asset_id": "<uuid>",
  "license_id": "<uuid>"
}

Las compras en el marketplace en POST /api/marketplace/purchase usan el mismo flujo x402 cuando está habilitado.

Flujo de memo heredado (obsoleto)

Cuando AGENTBUY_X402_LICENSE_PAYMENTS está desactivado, las licencias de pago usan un flujo de factura con memo manual. Prefiere purchase_license para nuevas integraciones.

create_license_invoice (heredado)

Heredado: crea una factura de memo USDC en Solana. Prefiere purchase_license cuando x402 esté habilitado.

Parámetro	Tipo	Requerido	Descripción
asset_id	string	Sí	UUID del activo de search_assets
license_id	string	Sí	UUID del nivel de licencia de license_options
agent_identifier	string	No	Por defecto, la cabecera x-agent-identifiers

Licencias gratuitas (precio $0) se otorgan inmediatamente y devuelven un objeto grant con URLs de entrega.

Licencias de pago devuelven invoice_id, payment_memo_id, amount_usdc, treasury_address e instrucciones de pago. Envía el monto exacto en USDC en Solana con el memo, luego verifica.

get_license_invoice_status (heredado)

Consulta el estado de la factura por invoice_id o payment_memo_id. Devuelve la concesión y las URLs de activos cuando se completa.

Parámetro	Tipo	Requerido	Descripción
invoice_id	string	Uno requerido	UUID de factura de create_license_invoice
payment_memo_id	string	Uno requerido	Memo de pago de create_license_invoice

Consulta hasta que el estado sea completed. El payload de concesión incluye cdn_url, thumbnail_url y source_download_url para paquetes/código.

verify_license_payment (heredado)

Escanea Solana en busca de un pago que coincida con el memo de la factura, completa el cumplimiento y devuelve el estado actualizado.

Parámetro	Tipo	Requerido	Descripción
invoice_id	string	Uno requerido	UUID de factura
payment_memo_id	string	Uno requerido	Memo de pago

Escanea Solana en busca de una transferencia entrante de USDC que coincida con el memo, completa el cumplimiento, paga la billetera del vendedor y devuelve el estado actualizado más las URLs de entrega de la concesión.

Payload de entrega de concesión

Después de una compra exitosa (gratuita o de pago), el objeto de concesión incluye:

{
  "grant_id": "uuid",
  "asset_id": "uuid",
  "license_id": "uuid",
  "license_title": "Commercial unrestricted",
  "cdn_url": "https://...",
  "thumbnail_url": "https://...",
  "source_download_url": "https://...",
  "source_format": "zip",
  "detailed_description": "...",
  "tags": ["surfing", "ocean"],
  "asset_category": "photos",
  "asset_subtype": null,
  "asset_kind": "raster",
  "granted_at": "2026-07-05T...",
  "receipt_url": "https://..."
}

Endpoints REST de conveniencia

Endpoint principal de compra:

POST https://agentbuy.shop/api/mcp/license/purchase
Content-Type: application/json
x-agent-identifiers: ["my-buyer-agent"]

{
  "asset_id": "<uuid>",
  "license_id": "<uuid>"
}

Flujo de memo heredado (solo con flag desactivado):

POST https://agentbuy.shop/api/mcp/invoice
Content-Type: application/json

{
  "asset_id": "<uuid>",
  "license_id": "<uuid>"
}

POST https://agentbuy.shop/api/mcp/verify
Content-Type: application/json

{
  "invoice_id": "<uuid>"
}

Flujo de compra de extremo a extremo

1. El agente llama a tools/list para descubrir las herramientas disponibles
2. El agente llama a search_assets con una consulta semántica que coincida con el brief de la campaña
3. El agente evalúa las vistas previas de watermarked_cdn_url (sin costo)
4. El agente selecciona asset_id + license_id de license_options
5. El agente llama a purchase_license (o POST /api/mcp/license/purchase)
6. Si es de pago: el agente recibe HTTP 402, firma el pago x402 en USDC, reintenta con PAYMENT-SIGNATURE
7. El agente recibe la concesión con cdn_url / source_download_url para uso en producción