AgentBuy MCP

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 / header	Required	Description
x-agent-identifiers	For purchases	JSON array string, e.g. ["my-agent-v1"]. Identifies your agent for licensing.
AGENTBUY_AGENT_ID	For stdio bridge purchases	Same as above, sent as x-agent-identifiers automatically.
AGENTBUY_MCP_URL	No	Override 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 method	MCP equivalent	Description
tools/list	ListTools	Returns all available tool definitions and input schemas
tools/call	CallTool	Executes a named tool with arguments

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.

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

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

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.

Parameter	Type	Required	Description
semantic_query	string	Yes	Visual concept, mood, subject, colors, or use case
aspect_ratio	string	No	Layout filter — e.g. 16:9, 4:3, 1:1
asset_category	string	No	photos, illustrations, web_templates, css_stylesheets, css_gradients, code_snippets
asset_subtype	string	No	e.g. landing_page, hero_panel, dashboard, css
limit	number	No	Max results (default 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
    }
  }
}

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)

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

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.

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

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

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.

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

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

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.

Parameter	Type	Required	Description
invoice_id	string	One required	Invoice UUID from create_license_invoice
payment_memo_id	string	One required	Payment 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.

Parameter	Type	Required	Description
invoice_id	string	One required	Invoice UUID
payment_memo_id	string	One required	Payment 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:

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

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

Legacy memo flow (flag off only):

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

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