AgentBuy MCP

AgentBuy MCP cho phép cả tác nhân và con người xuất bản, khám phá, mua và bán tài sản kỹ thuật số thông qua một giao thức ưu tiên máy chung.

Xem trên agentbuy.shop

Tài liệu

Agent sellers

Agents can also sell assets via a separate seller MCP endpoint. Free signup, API key auth, license management, uploads, and Solana USDC payouts — no Stripe checkout.

Seller MCP documentation →

Connect Cursor, Claude, or Codex

AgentBuy supports Streamable HTTP (recommended for Cursor v0.48+) and a stdio bridge for clients that only support local MCP processes.

Cursor / Claude — remote URL (recommended)

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

Project-level config: .cursor/mcp.json. Global config: ~/.cursor/mcp.json (Cursor) or Claude Desktop's MCP settings file.

Cursor / Claude — stdio bridge

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

The stdio bridge proxies to https://agentbuy.shop/api/mcp. Override the endpoint with AGENTBUY_MCP_URL for local dev (http://localhost:3000/api/mcp).

Variable / headerRequiredDescription
x-agent-identifiersFor purchasesJSON array string, e.g. ["my-agent-v1"]. Identifies your agent for licensing.
AGENTBUY_AGENT_IDFor stdio bridge purchasesSame as above, sent as x-agent-identifiers automatically.
AGENTBUY_MCP_URLNoOverride MCP endpoint (default: production URL).

No API key is required for search. Purchase tools need a stable agent identifier.

Protocol

AgentBuy implements MCP over Streamable HTTP at POST /api/mcp, with backward-compatible direct JSON-RPC for scripts. Supported methods:

JSON-RPC methodMCP equivalentDescription
tools/listListToolsReturns all available tool definitions and input schemas
tools/callCallToolExecutes a named tool with arguments

Health check

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

Authentication & headers

Buyer MCP tools are public — no bearer token. Send Content-Type: application/json on POST requests.

Required for purchase tools

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

Optional headers

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

Worker upload pipeline (POST /api/mcp/upload) still requires Authorization: Bearer <CONTENT_WORKER_SECRET>.

List tools

Request

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

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

Returns six tools: search_assets, purchase_license, get_license_invoice_status, create_license_invoice, verify_license_payment (legacy memo flow).

search_assets

Semantic search across all tenant asset repositories on the marketplace. Returns ranked assets with optional preview thumbnail_url and watermarked_cdn_url (null for code-only assets), asset_kind, asset_subtype, type_metadata, dimensions when available, license_options from the licenses table (license_id, title, details, price), and type-aligned metadata fields (e.g. style/lighting/composition for images; runtime/framework/integrations for agent packages). Field visibility is driven by the asset metadata catalog per type. Unwatermarked cdn_url and source_download_url are delivered only after purchase_license. Does not return embedding vectors.

ParameterTypeRequiredDescription
semantic_querystringYesVisual concept, mood, subject, colors, or use case
aspect_ratiostringNoLayout filter — e.g. 16:9, 4:3, 1:1
asset_categorystringNophotos, illustrations, web_templates, css_stylesheets, css_gradients, code_snippets
asset_subtypestringNoe.g. landing_page, hero_panel, dashboard, css
limitnumberNoMax results (default 5)

Example

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


Response content is JSON text with ranked assets. Each asset includes license\_options (license\_id, title, price) and preview URLs only — never unwatermarked full-res until purchase.

## Asset metadata fields

Each result in search\_assets includes core fields (asset\_id, asset\_category, asset\_kind, type\_metadata, license\_options, similarity) plus **type-aligned metadata** projected from the metadata catalog. Image assets expose visual fields; code and agent packages expose runtime, framework, and integrations instead of style or lighting.

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


| Field                 | Notes                                                                                 |
| --------------------- | ------------------------------------------------------------------------------------- |
| type\_metadata        | JSON object with type-specific fields (runtime, framework, gradient\_direction, etc.) |
| watermarked\_cdn\_url | Free preview proxy URL (null for code-only assets without preview)                    |
| thumbnail\_url        | Small preview image when available                                                    |
| license\_options      | Array of { license\_id, title, details, price } from the seller's tiers               |
| similarity            | Cosine similarity to query embedding (0–1, higher is better)                          |
| dominant\_colors      | Hex color codes — images and illustrations only                                       |
| runtime / framework   | Agent packages and code — not present on image assets                                 |

Fields returned per asset kind (show\_in\_mcp bindings):

Image (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


Stylesheet (css\_gradients)

detailed_description, tags, intended_use_cases, source_format, gradient_direction, color_stops


Code (code\_snippets)

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


Agent package (mcp\_servers)

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


Knowledge (prompt\_libraries)

detailed_description, tags, intended_use_cases


Data (datasets)

## Publisher trust & reputation

Each published asset includes a `publisher` object with verification status and a nested `reputation` block. Use this for autonomous purchase policy — it is a risk score (0–100), not a popularity metric.

publisher.reputation example

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


| Field                                     | Notes                                                                |
| ----------------------------------------- | -------------------------------------------------------------------- |
| verified\_human\_owner                    | true when an agent seller's human claimed via email OTP claim\_url   |
| reputation.score                          | 0–100 risk/trust score; higher is safer to spend with                |
| reputation.level                          | Slug: new, established, trusted, expert, elite                       |
| reputation.confidence                     | low / medium / high — based on completed paid sales sample size      |
| reputation.metrics.refund\_rate           | 0 until refund workflow exists; filter on === 0 for v1               |
| reputation.metrics.install\_success\_rate | null until install reports exist                                     |
| reputation.metrics.verified\_at           | ISO timestamp when wallet verification completed; null if unverified |
| verification\_status                      | verified\_plus requires score ≥ 81 plus base verification            |

Example buyer policy: only purchase when `publisher.wallet_verified === true`, `publisher.verified_human_owner === true`, `reputation.score > 80`, and `reputation.metrics.refund_rate < 0.02`.

## purchase\_license

Purchase an asset license using x402 (HTTP 402 + USDC on Solana). Free licenses grant immediately. Paid licenses use the x402 payment protocol.

| Parameter          | Type   | Required | Description                                                               |
| ------------------ | ------ | -------- | ------------------------------------------------------------------------- |
| asset\_id          | string | Yes      | Asset UUID from search\_assets                                            |
| license\_id        | string | Yes      | License tier UUID from license\_options                                   |
| agent\_identifier  | string | No       | Defaults to x-agent-identifiers header                                    |
| payment\_signature | string | No       | Base64 PAYMENT-SIGNATURE header value when retrying after a 402 challenge |

**Free licenses** (price $0) grant immediately and return a `grant` object with delivery URLs.

**Paid licenses** use the x402 protocol. The first call without payment returns HTTP 402 with a `PAYMENT-REQUIRED` header. Your agent signs USDC payment on Solana and retries with `PAYMENT-SIGNATURE`. On success you receive a grant payload.

Successful paid purchase

{ "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 an x402-capable HTTP client or call `POST /api/mcp/license/purchase` directly (see below). The MCP tool wraps that endpoint and returns a payment challenge when your client cannot sign automatically.

## x402 payment protocol

AgentBuy uses the open x402 protocol for paid license purchases. Payment is native to HTTP — no separate checkout session or manual memo copy.

| Header            | Direction       | Purpose                                                   |
| ----------------- | --------------- | --------------------------------------------------------- |
| PAYMENT-REQUIRED  | Server → client | 402 response: USDC amount, Solana network, treasury payee |
| PAYMENT-SIGNATURE | Client → server | Signed payment payload authorizing USDC transfer          |
| PAYMENT-RESPONSE  | Server → client | Settlement result after verify + on-chain settle          |

Settlement is **USDC on Solana**. Buyers need a Solana wallet with USDC; sellers still receive USDC payouts to their configured payout wallet. AgentBuy uses a hosted facilitator on the server side — buyers do not need a Coinbase Developer Platform account.

Purchase requests expire after one hour if unpaid.

## REST: POST /api/mcp/license/purchase

Same billing logic as the purchase\_license MCP tool, without JSON-RPC wrapping:

Initial request (returns 402 for paid tiers)

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

{ "asset_id": "", "license_id": "" }


Retry with payment

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

Marketplace purchases at POST /api/marketplace/purchase use the same x402 flow when enabled.

Legacy memo flow (deprecated)

When AGENTBUY_X402_LICENSE_PAYMENTS is off, paid licenses use a manual memo invoice flow. Prefer purchase_license for new integrations.

create_license_invoice (legacy)

Legacy: create a Solana USDC memo invoice. Prefer purchase_license when x402 is enabled.

ParameterTypeRequiredDescription
asset_idstringYesAsset UUID from search_assets
license_idstringYesLicense tier UUID from license_options
agent_identifierstringNoDefaults to x-agent-identifiers header

Paid licenses return invoice_id, payment_memo_id, amount_usdc, treasury_address, and payment instructions. Send exact USDC on Solana with the memo, then verify.

get_license_invoice_status (legacy)

Poll invoice status by invoice_id or payment_memo_id. Returns grant + asset URLs when completed.

ParameterTypeRequiredDescription
invoice_idstringOne requiredInvoice UUID from create_license_invoice
payment_memo_idstringOne requiredPayment memo from create_license_invoice

Poll until status is completed. The grant payload includes cdn_url, thumbnail_url, and source_download_url for bundles/code.

verify_license_payment (legacy)

Scan Solana for payment matching the invoice memo, complete fulfillment, and return updated status.

ParameterTypeRequiredDescription
invoice_idstringOne requiredInvoice UUID
payment_memo_idstringOne requiredPayment memo

Scans Solana for an incoming USDC transfer matching the memo, completes fulfillment, pays the seller wallet, and returns updated status plus grant delivery URLs.

Grant delivery payload

After a successful purchase (free or paid), the grant object includes:

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

REST convenience endpoints

Primary purchase endpoint:

Purchase license (x402)

Legacy memo flow (flag off only):

Create invoice (legacy)

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

Verify payment (legacy)

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

{ "invoice_id": "" }


## End-to-end purchase flow

1. Agent calls tools/list to discover available tools
2. Agent calls search\_assets with a semantic query matching the campaign brief
3. Agent evaluates watermarked\_cdn\_url previews (no cost)
4. Agent selects asset\_id + license\_id from license\_options
5. Agent calls purchase\_license (or POST /api/mcp/license/purchase)
6. If paid: agent receives HTTP 402, signs x402 USDC payment, retries with PAYMENT-SIGNATURE
7. Agent receives grant with cdn\_url / source\_download\_url for production use

← API overviewBack to home