AdSpoty

AdSpoty Agent Integrations (MCP)

Connect ChatGPT, Claude, Cursor, or any Model Context Protocol client to query AdSpoty listings.

MCP endpoint
https://adspoty.com/mcp
Add this URL in your MCP client's connector settings. Public read-only, no auth required.
Health checkAdmin console →

Available tools

list_categories
read-only
List categories

List AdSpoty marketplace categories. Pass a parent_slug to walk into subcategories.

Inputs
  • parent_slug : string — Omit for top-level categories.
Example calls
Top-level categories
{
  "tool": "list_categories",
  "arguments": {}
}
Subcategories under 'vehicles'
{
  "tool": "list_categories",
  "arguments": {
    "parent_slug": "vehicles"
  }
}
Error cases
Unknown parent slug
{
  "tool": "list_categories",
  "arguments": {
    "parent_slug": "not-a-real-slug"
  }
}
Response:
{"isError": true, "content": [{"type":"text","text":"Error: Unknown parent_slug 'not-a-real-slug'."}]}
search_listings
read-only
Search listings

Find active listings by keyword, category slug, city, and/or price range. Supports pagination (limit + offset) and stable sorting. Results include tier flags (spotlight/featured/urgent/bumped/highlighted) and a public URL. Response includes count, total, offset, next_offset.

Inputs
  • query : string — Free-text over title & description.
  • category_slug : string
  • city : string
  • min_price : number
  • max_price : number
  • limit : number — 1–50, default 20.
  • offset : number — 0–10000, default 0. Use response.next_offset to page.
  • sort : enum — relevance | newest | oldest | price_asc | price_desc. All sorts add a stable id tiebreak.
Example calls
Search 'iphone' under $500
{
  "tool": "search_listings",
  "arguments": {
    "query": "iphone",
    "max_price": 500
  }
}
Vehicles in Miami, cheapest first
{
  "tool": "search_listings",
  "arguments": {
    "category_slug": "vehicles",
    "city": "Miami",
    "sort": "price_asc"
  }
}
Page 2 (offset 20, size 20)
{
  "tool": "search_listings",
  "arguments": {
    "query": "bike",
    "limit": 20,
    "offset": 20
  }
}
Error cases
min_price > max_price
{
  "tool": "search_listings",
  "arguments": {
    "min_price": 500,
    "max_price": 100
  }
}
Response:
{"isError": true, "content": [{"type":"text","text":"Error: min_price cannot be greater than max_price."}]}
Unknown category_slug
{
  "tool": "search_listings",
  "arguments": {
    "category_slug": "not-a-real-slug"
  }
}
Response:
{"isError": true, "content": [{"type":"text","text":"Error: Unknown category_slug: 'not-a-real-slug'."}]}
Invalid limit (>50)
{
  "tool": "search_listings",
  "arguments": {
    "limit": 999
  }
}
Response:
Zod validation error — limit must be ≤ 50. The MCP transport returns a JSON-RPC error before the handler runs.
get_listing
read-only
Get listing details

Fetch full details for a listing. Pass either a raw UUID as `id`, or a listing URL / path segment containing the UUID as `slug`.

Inputs
  • id : uuid — Raw listing UUID.
  • slug : string — Full listing URL (e.g. https://adspoty.com/listing/<uuid>) or path segment.
Example calls
By UUID
{
  "tool": "get_listing",
  "arguments": {
    "id": "37b2e0dd-e350-4cc2-a372-c9199caafb64"
  }
}
By URL
{
  "tool": "get_listing",
  "arguments": {
    "slug": "https://adspoty.com/listing/37b2e0dd-e350-4cc2-a372-c9199caafb64"
  }
}
Error cases
Missing identifier
{
  "tool": "get_listing",
  "arguments": {}
}
Response:
{"isError": true, "content": [{"type":"text","text":"Provide `id` (UUID) or `slug` (a listing URL / path containing the UUID)."}]}
Not found / inactive
{
  "tool": "get_listing",
  "arguments": {
    "id": "00000000-0000-0000-0000-000000000000"
  }
}
Response:
{"isError": true, "content": [{"type":"text","text":"Listing not found or not active."}]}
Malformed UUID in slug
{
  "tool": "get_listing",
  "arguments": {
    "slug": "https://adspoty.com/listing/not-a-uuid"
  }
}
Response:
{"isError": true, "content": [{"type":"text","text":"Provide `id` (UUID) or `slug` (a listing URL / path containing the UUID)."}]}
Error response format

All tool errors follow the MCP standard: the tool returns a normal result object with isError: true and a human-readable message inside content[].text. Input-validation failures (wrong types, out-of-range numbers) are rejected by the JSON-RPC transport before the handler runs and surface as a JSON-RPC error object instead. Rate-limit (429) and method-not-allowed (405) responses come from the HTTP layer and never enter the MCP tool envelope.

{
  "isError": true,
  "content": [{ "type": "text", "text": "Error: <human-readable message>" }]
}
Quick prompt to try in your agent
"Use the adspoty-mcp connector: list the top-level categories, then find up to 5 active listings under 'vehicles' in Miami priced below $10,000. Share the URLs."