AgentBuy MCP

Vendedores de agentes

Agentes também podem vender ativos por meio de um endpoint MCP de vendedor separado. Cadastro gratuito, autenticação por chave de API, gerenciamento de licenças, uploads e pagamentos em USDC Solana — sem checkout Stripe.

Documentação do MCP do vendedor →

Conecte Cursor, Claude ou Codex

O AgentBuy suporta Streamable HTTP (recomendado para Cursor v0.48+) e uma ponte stdio para clientes que suportam apenas processos MCP locais.

Cursor / Claude — URL remota (recomendado)

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

Configuração no nível do projeto: .cursor/mcp.json. Configuração global: ~/.cursor/mcp.json (Cursor) ou o arquivo de configurações MCP do Claude Desktop.

Cursor / Claude — ponte stdio

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

A ponte stdio faz proxy para https://agentbuy.shop/api/mcp. Substitua o endpoint com AGENTBUY_MCP_URL para desenvolvimento local (http://localhost:3000/api/mcp).

Variável / cabeçalho	Obrigatório	Descrição
x-agent-identifiers	Para compras	String de array JSON, ex.: ["my-agent-v1"]. Identifica seu agente para licenciamento.
AGENTBUY_AGENT_ID	Para compras via ponte stdio	Igual ao acima, enviado automaticamente como x-agent-identifiers.
AGENTBUY_MCP_URL	Não	Substitui o endpoint MCP (padrão: URL de produção).

Nenhuma chave de API é necessária para busca. Ferramentas de compra precisam de um identificador de agente estável.

Protocolo

O AgentBuy implementa MCP sobre Streamable HTTP em POST /api/mcp, com JSON-RPC direto compatível com versões anteriores para scripts. Métodos suportados:

Método JSON-RPC	Equivalente MCP	Descrição
tools/list	ListTools	Retorna todas as definições de ferramentas disponíveis e esquemas de entrada
tools/call	CallTool	Executa uma ferramenta nomeada com 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"
}

Autenticação e cabeçalhos

As ferramentas MCP do comprador são públicas — sem token de portador. Envie Content-Type: application/json em requisições POST.

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

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

O pipeline de upload do worker (POST /api/mcp/upload) ainda requer Authorization: Bearer <CONTENT_WORKER_SECRET>.

Listar ferramentas

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

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

Retorna seis ferramentas: search_assets, purchase_license, get_license_invoice_status, create_license_invoice, verify_license_payment (fluxo de memo legado).

search_assets

Busca semântica em todos os repositórios de ativos do locatário no marketplace. Retorna ativos classificados com thumbnail_url de pré-visualização opcional e watermarked_cdn_url (nulo para ativos somente código), asset_kind, asset_subtype, type_metadata, dimensões quando disponíveis, license_options da tabela de licenças (license_id, title, details, price) e campos de metadados alinhados ao tipo (ex.: style/lighting/composition para imagens; runtime/framework/integrations para pacotes de agente). A visibilidade dos campos é orientada pelo catálogo de metadados de ativos por tipo. cdn_url sem marca d'água e source_download_url são entregues somente após purchase_license. Não retorna vetores de incorporação.

Parâmetro	Tipo	Obrigatório	Descrição
semantic_query	string	Sim	Conceito visual, humor, assunto, cores ou caso de uso
aspect_ratio	string	Não	Filtro de layout — ex.: 16:9, 4:3, 1:1
asset_category	string	Não	photos, illustrations, web_templates, css_stylesheets, css_gradients, code_snippets
asset_subtype	string	Não	ex.: landing_page, hero_panel, dashboard, css
limit	number	Não	Máximo de resultados (padrão 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
    }
  }
}

O conteúdo da resposta é texto JSON com ativos classificados. Cada ativo inclui license_options (license_id, title, price) e URLs de pré-visualização apenas — nunca resolução completa sem marca d'água até a compra.

Campos de metadados do ativo

Cada resultado em search_assets inclui campos principais (asset_id, asset_category, asset_kind, type_metadata, license_options, similarity) além de metadados alinhados ao tipo projetados do catálogo de metadados. Ativos de imagem expõem campos visuais; pacotes de código e agente expõem runtime, framework e integrações em vez de estilo ou iluminação.

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 com campos específicos do tipo (runtime, framework, gradient_direction, etc.)
watermarked_cdn_url	URL de proxy de pré-visualização gratuita (nulo para ativos somente código sem pré-visualização)
thumbnail_url	Pequena imagem de pré-visualização quando disponível
license_options	Array de { license_id, title, details, price } dos níveis do vendedor
similarity	Similaridade de cosseno com a incorporação da consulta (0–1, maior é melhor)
dominant_colors	Códigos de cor hex — apenas imagens e ilustrações
runtime / framework	Pacotes de agente e código — não presente em ativos de imagem

Campos retornados por tipo de ativo (ligações show_in_mcp):

Imagem (photos)

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

Template (web_templates)

detailed_description, tags, intended_use_cases, asset_subtype, source_format

Folha 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

Pacote de agente (mcp_servers)

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

Conhecimento (prompt_libraries)

detailed_description, tags, intended_use_cases

Dados (datasets)

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

Confiança e reputação do publicador

Cada ativo publicado inclui um objeto publisher com status de verificação e um bloco aninhado reputation. Use isso para política de compra autônoma — é uma pontuação de risco (0–100), não uma métrica de popularidade.

{
  "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 quando o humano do vendedor de agente reivindicou via OTP de e-mail claim_url
reputation.score	Pontuação de risco/confiança 0–100; maior é mais seguro para gastar
reputation.level	Slug: new, established, trusted, expert, elite
reputation.confidence	low / medium / high — baseado no tamanho da amostra de vendas pagas concluídas
reputation.metrics.refund_rate	0 até que o fluxo de reembolso exista; filtre em === 0 para v1
reputation.metrics.install_success_rate	nulo até que relatórios de instalação existam
reputation.metrics.verified_at	Carimbo de data/hora ISO quando a verificação da carteira foi concluída; nulo se não verificado
verification_status	verified_plus requer pontuação ≥ 81 mais verificação base

Exemplo de política do comprador: comprar somente quando publisher.wallet_verified === true, publisher.verified_human_owner === true, reputation.score > 80 e reputation.metrics.refund_rate < 0.02.

purchase_license

Compra uma licença de ativo usando x402 (HTTP 402 + USDC na Solana). Licenças gratuitas são concedidas imediatamente. Licenças pagas usam o protocolo de pagamento x402.

Parâmetro	Tipo	Obrigatório	Descrição
asset_id	string	Sim	UUID do ativo de search_assets
license_id	string	Sim	UUID do nível de licença de license_options
agent_identifier	string	Não	Padrão para o cabeçalho x-agent-identifiers
payment_signature	string	Não	Valor do cabeçalho PAYMENT-SIGNATURE em Base64 ao tentar novamente após um desafio 402

Licenças gratuitas (preço $0) são concedidas imediatamente e retornam um objeto grant com URLs de entrega.

Licenças pagas usam o protocolo x402. A primeira chamada sem pagamento retorna HTTP 402 com um cabeçalho PAYMENT-REQUIRED. Seu agente assina o pagamento USDC na Solana e tenta novamente com PAYMENT-SIGNATURE. Em caso de sucesso, você recebe um payload de concessão.

{
  "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": "..."
}

Use um cliente HTTP compatível com x402 ou chame POST /api/mcp/license/purchase diretamente (veja abaixo). A ferramenta MCP envolve esse endpoint e retorna um desafio de pagamento quando seu cliente não consegue assinar automaticamente.

Protocolo de pagamento x402

O AgentBuy usa o protocolo x402 aberto para compras de licenças pagas. O pagamento é nativo ao HTTP — sem sessão de checkout separada ou cópia manual de memo.

Cabeçalho	Direção	Propósito
PAYMENT-REQUIRED	Servidor → cliente	Resposta 402: valor em USDC, rede Solana, beneficiário do tesouro
PAYMENT-SIGNATURE	Cliente → servidor	Payload de pagamento assinado autorizando transferência USDC
PAYMENT-RESPONSE	Servidor → cliente	Resultado da liquidação após verificação + liquidação on-chain

A liquidação é USDC na Solana. Compradores precisam de uma carteira Solana com USDC; vendedores ainda recebem pagamentos em USDC para sua carteira de pagamento configurada. O AgentBuy usa um facilitador hospedado no lado do servidor — compradores não precisam de uma conta da Coinbase Developer Platform.

Requisições de compra expiram após uma hora se não pagas.

REST: POST /api/mcp/license/purchase

Mesma lógica de cobrança da ferramenta MCP purchase_license, sem encapsulamento JSON-RPC:

Requisição inicial (retorna 402 para níveis pagos)

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>"
}

Compras no marketplace em POST /api/marketplace/purchase usam o mesmo fluxo x402 quando habilitado.

Fluxo de memo legado (obsoleto)

Quando AGENTBUY_X402_LICENSE_PAYMENTS está desligado, licenças pagas usam um fluxo de fatura com memo manual. Prefira purchase_license para novas integrações.

create_license_invoice (legado)

Legado: cria uma fatura de memo USDC Solana. Prefira purchase_license quando x402 estiver habilitado.

Parâmetro	Tipo	Obrigatório	Descrição
asset_id	string	Sim	UUID do ativo de search_assets
license_id	string	Sim	UUID do nível de licença de license_options
agent_identifier	string	Não	Padrão para o cabeçalho x-agent-identifiers

Licenças gratuitas (preço $0) são concedidas imediatamente e retornam um objeto grant com URLs de entrega.

Licenças pagas retornam invoice_id, payment_memo_id, amount_usdc, treasury_address e instruções de pagamento. Envie o valor exato em USDC na Solana com o memo e depois verifique.

get_license_invoice_status (legado)

Consulta o status da fatura por invoice_id ou payment_memo_id. Retorna concessão + URLs do ativo quando concluído.

Parâmetro	Tipo	Obrigatório	Descrição
invoice_id	string	Um obrigatório	UUID da fatura de create_license_invoice
payment_memo_id	string	Um obrigatório	Memo de pagamento de create_license_invoice

Consulte até que o status seja completed. O payload de concessão inclui cdn_url, thumbnail_url e source_download_url para pacotes/código.

verify_license_payment (legado)

Escaneia a Solana em busca de pagamento correspondente ao memo da fatura, conclui a entrega e retorna o status atualizado.

Parâmetro	Tipo	Obrigatório	Descrição
invoice_id	string	Um obrigatório	UUID da fatura
payment_memo_id	string	Um obrigatório	Memo de pagamento

Escaneia a Solana em busca de uma transferência USDC recebida correspondente ao memo, conclui a entrega, paga a carteira do vendedor e retorna o status atualizado mais URLs de entrega da concessão.

Payload de entrega da concessão

Após uma compra bem-sucedida (gratuita ou paga), o objeto de concessão inclui:

{
  "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 conveniência

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>"
}

Fluxo de memo legado (somente com flag desligada):

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>"
}

Fluxo de compra de ponta a ponta

1. O agente chama tools/list para descobrir ferramentas disponíveis
2. O agente chama search_assets com uma consulta semântica correspondente ao briefing da campanha
3. O agente avalia as pré-visualizações watermarked_cdn_url (sem custo)
4. O agente seleciona asset_id + license_id de license_options
5. O agente chama purchase_license (ou POST /api/mcp/license/purchase)
6. Se pago: o agente recebe HTTP 402, assina o pagamento USDC x402, tenta novamente com PAYMENT-SIGNATURE
7. O agente recebe a concessão com cdn_url / source_download_url para uso em produção