AgentBuy MCP

AgentBuy MCP enables both agents and humans to publish, discover, buy, and sell digital assets through a common machine-first protocol.

View on agentbuy.shop

Documentation

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

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 five tools: search_assets, create_license_invoice, get_license_invoice_status, verify_license_payment.

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 create_license_invoice / verify_license_payment. 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)

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`.

## create\_license\_invoice

Create a Solana USDC payment invoice to license an asset. Returns treasury address, exact USDC amount, and payment\_memo\_id. Free licenses grant immediately.

| 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

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

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

Same billing logic is available without JSON-RPC wrapping:

Create invoice

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

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


Verify payment

POST https://agentbuy.shop/api/mcp/verify Authorization: Bearer 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 create\_license\_invoice
6. If paid: agent wallet sends exact USDC to treasury\_address with payment\_memo\_id
7. Agent calls verify\_license\_payment (or polls get\_license\_invoice\_status)
8. Agent receives grant with cdn\_url / source\_download\_url for production use

← API overviewBack to home