API: Connect AI apps

ListingView runs an MCP server, so an AI app can research the Etsy market and work with your listings, files, presets, Etsy drafts and live listings. The app connects with one of your API keys.

Server URL: https://api.listingview.io/mcp

Supported today: Claude Code and Cursor. If you haven't made a key yet, start with API: Getting started. For what each kind of key can do and how the drafts workflow runs, see Using the ListingView API, MCP server & CLI.

Set up

Create a key in ListingView under Settings → API Keys. When the key is shown, the MCP config tab under Connect it has a config with your key already filled in. It looks like this:

{
  "mcpServers": {
    "listingview-drafts": {
      "type": "http",
      "url": "https://api.listingview.io/mcp",
      "headers": {
        "Authorization": "Bearer lv_live_…"
      }
    }
  }
}

Name the entry listingview-drafts for a Drafting Agent key, which can create Etsy drafts. Name it listingview-publish for a Publisher key, and listingview for any other key.

Claude Code

Add the server from your terminal:

claude mcp add --transport http listingview-drafts https://api.listingview.io/mcp \
  --header "Authorization: Bearer lv_live_…"

Or put the entry in your project's .mcp.json. To keep the key out of a file you might commit, write the header with an environment variable and set LISTINGVIEW_API_KEY in your shell. Claude Code fills it in.

{
  "mcpServers": {
    "listingview-drafts": {
      "type": "http",
      "url": "https://api.listingview.io/mcp",
      "headers": {
        "Authorization": "Bearer ${LISTINGVIEW_API_KEY}"
      }
    }
  }
}

Cursor

Put the same entry in ~/.cursor/mcp.json for all your projects, or in .cursor/mcp.json inside one project.

Claude Desktop and claude.ai (coming soon)

Claude Desktop and custom connectors on claude.ai are coming soon. They need a sign-in, which API keys don't support yet.

One ListingView server per app or chat

You'll see this warning under every MCP config in ListingView:

Use this key in its own app or chat. Don't add your drafting and publishing keys to the same chat or agent: enabling both in one chat removes the split; prompt-injected listing text could then publish.

Set up exactly one ListingView server entry in each app or chat. A Drafting Agent key can never publish, and a Publisher key can never create drafts. That split only protects you while the two keys stay in separate apps or chats. If both were enabled in one chat, text hidden in a listing could steer the agent into publishing.

So give your listingview-drafts server and your listingview-publish server separate apps or chats. API: Getting started explains the two-key setup.

Tools

ListingView's MCP server has 25 tools. Your app sees only the tools your key can use on your current plan. When you create a key, Settings shows how many tools it gives your agent. Each tool below lists the scope it needs and the lowest plan that includes it. The scopes list explains each scope.

Market research

• research_keywords: research Etsy keywords. Scope research:read. Scout and above.

• research_search_listings: search Etsy market listings. Scope research:read. Scout and above.

• research_search_shops: search Etsy market shops. Scope research:read. Scout and above.

• research_listing_details: analyze one Etsy listing. Scope research:read. Scout and above.

• research_shop_analysis: analyze one Etsy shop. Scope research:read. Scout and above.

• research_compare_shops: compare Etsy shops. Scope research:read. Scout and above.

• research_tag_analysis: analyze Etsy tags. Scope research:read. Scout and above.

• research_tag_ideas: get Etsy tag ideas. Scope research:read. Scout and above.

Listing rows are refreshed from Etsy as they are served, or come back as pointers. API: Limits & budgets explains both.

Your shop and usage

• my_shop_performance: my shop's performance. Scope research:read. Scout and above.

• get_account_usage: check API usage and budgets. Scope research:read. Scout and above.

Listings in ListingView (nothing here changes Etsy)

• list_my_listings: list my ListingView listings. Scope catalog:read. Scout and above.

• get_listing: get my listings. Fetch one listing by ListingView or Etsy id, or look up to 100 Etsy listing ids at once (etsy_listing_ids). include adds their live Etsy state, print-on-demand prices or live inventory. Only your own shops. Scope catalog:read. Scout and above.

• create_local_listing: create a ListingView listing (not on Etsy). Scope catalog:write, plus assets:write for {import_url} images. Plus and above.

• update_listing: edit a ListingView listing (not on Etsy). Scope catalog:write, plus assets:write for {import_url} images. Scout and above.

• bulk_edit_listings: bulk edit ListingView listings (not on Etsy). It edits or creates up to 100 listings in one job; poll the job with get_bulk_job_status. Creating listings this way needs an idempotency_key: the same key and arguments return the first job. Scope catalog:write, plus assets:write for {import_url} images. Plus and above.

• enhance_listing_with_ai: suggest AI listing copy (spends AI tokens). Pass current_copy to improve copy you already have instead of writing from scratch. use_custom_instructions is on by default and adds the seller's saved Custom Instructions to your instructions. Scope catalog:write. Plus and above for an existing listing, Scout and above for copy from artwork.

Asset library

• list_assets: browse my asset library. kind: "deliverable" lists the files your digital listings deliver to buyers. Scope catalog:read. Scout and above.

• add_assets: add files to my asset library. Designs and photos are PNG, JPEG or WebP. With purpose: "digital_file", it adds the files a digital listing delivers to buyers (PDF, ZIP, SVG, fonts, audio and more). Scope assets:write. Scout and above. See API: Uploads.

• organize_assets: organize my asset library. Scope assets:write. Scout and above.

Presets

• list_presets: list presets and what you build them from. Scope presets:read. Scout and above. List your presets, or fetch one with include; include: "spec" returns the exact shape manage_preset accepts. Or browse what presets are made of with view:

  • pod_products: search print-on-demand products, then pass product_id for its print providers, and provider_id for colors, sizes, costs and print areas;

  • category_attributes, shop_profiles and mockup_templates.

• manage_preset: create, edit or copy a preset: print-on-demand (products, providers, colors and sizes, prices, placements, design slots, mockups), digital (delivery files) or physical (variations, attributes). A copy can swap a print-on-demand product for one from another preset. It never changes Etsy listings. Scope presets:write. Scout and above for digital and physical presets, Plus and above for print-on-demand presets.

Build presets with the API walks through both tools.

Etsy drafts and jobs

• create_etsy_drafts: create, stage or submit Etsy drafts (not live). Scope etsy_drafts:write, plus catalog:write if you use ai_copy. Plus and above. It WRITES ETSY DRAFTS: draft listings in your real Etsy shop, from a preset. Drafts are never visible to buyers, and a key that can use this tool can never publish. Choose the operation:

  • create (the default): make the drafts now;

  • stage: save the batch for the seller to review under Saved listings; nothing reaches Etsy;

  • update: change a staged batch;

  • submit: send a staged batch as it is now, including the seller's edits.

• get_bulk_job_status: check jobs and staged batches. It checks a job's progress and per-item results, including reprice jobs (their job_id starts lbj_). list: "jobs" lists your Etsy-draft job history, and list: "staged" lists batches waiting for review. draft_id reads one batch as it is now, including the seller's edits. Scope catalog:read or etsy_drafts:write. Reading one Etsy-draft job needs Plus and above. The lists and staged batches stay readable below Plus for a key that holds catalog:read.

Stage Etsy drafts, review them in ListingView, then submit walks through the whole loop.

Deletes

• delete_preset_or_draft: delete a preset or a draft. It PERMANENTLY DELETES one thing, so agents should call it only when the person asks for that deletion. kind is required and says which:

  • preset with preset_id: a ListingView preset. Scope presets:write. Scout and above.

  • staged_batch with draft_id: a batch you staged and haven't submitted. Nothing on Etsy changes, and its designs stay in your library. Scope etsy_drafts:write. Plus and above.

  • etsy_draft with listing_id or etsy_listing_id (never both), and shop_id: a DRAFT listing that ListingView created in your real Etsy shop, with its ListingView row and Printify product. It is refused if the listing is live or wasn't made by your ListingView Bulk Create. When other ListingView accounts share the shop, it also needs confirm_shared_delete: true. Scope etsy_drafts:write. Plus and above.

To remove one item from a staged batch, don't delete the batch: use create_etsy_drafts with operation: "update".

Publishing

• push_listing_live: publish to Etsy (live — needs a confirm step). It GOES LIVE ON ETSY. action is required:

  • push with listing_id: push one listing's saved edits;

  • push with listing_ids (Etsy listing ids) and pod_prices: reprice up to 20 live print-on-demand listings in one confirmation. A reprice changes prices only;

  • publish with listing_id: publish one listing.

  Every call shows what will change and waits for a confirmation. Scope catalog:live_write. Plus and above. See Publish and reprice live listings.

An argument with a fixed set of values, such as view, kind, operation, action, list or purpose, refuses anything else with VALIDATION_FAILED and candidates listing the values that work. Arguments that match none of a tool's modes answer VALIDATION_FAILED with the reason no_route, and details.errors[] says which argument to send, fix or drop. create_etsy_drafts with a draft_id and no operation is refused. It never submits by default.

What to expect

• Untrusted text. Results can carry text written by sellers, Etsy or an AI model, such as titles, tags, file names and AI copy. The server marks that text and wraps it in <untrusted-content source="listingview">, with a one-line warning above it. Your agent should treat it as data, never as instructions.

• Safe retries. Tools that change data take an idempotency_key argument, and some require it. Repeating a call with the same key returns the first result instead of doing the work twice.

• Errors. A failed tool call comes back as a tool error carrying the same error object as the REST API: code, message, details, docs_url and request_id. A refused call lists every problem at once in details.errors. Every code is listed on the errors page.

• When to retry. Give your agent the retry rules in API: Getting started. In short: re-read and retry after a conflict, wait retry_after after a retryable error, stop after 3 tries, and check the shop or read the job before acting on an unknown outcome.

• Next-call hints. When a message points to another call, it names the tool and its arguments, not a REST route.

• Budgets. MCP calls share your account's budgets with the REST API and the CLI. After a budget error, call get_account_usage. See API: Limits & budgets.

• Uploads from a chat. Most chat apps can't send files to ListingView themselves. Use the import_url mode of add_assets with a public image link, or upload the file in Asset Library and tell the agent its name. See API: Uploads.

• Test keys. With an lv_test_ key, every change is a dry run: the tool answers with dry_run: true and what would have happened, and nothing changes. Reads are real and use your API credits. See Rehearse with a test key in API: Getting started.

Troubleshooting

• The app can't connect. The server speaks the stateless MCP revision 2026-07-28. An app that only speaks an older revision gets an error that says so. Update the app.

• Every call fails with an authorization error. Check the key in the Authorization header. It may be mistyped, revoked or expired.

• A tool you expect is missing. The key doesn't hold the scope it needs, or your plan doesn't include it. Create a key with the right preset.

• A call is refused with candidates. An argument such as view, kind or operation has a value the tool doesn't know, or is missing. Pick one of the candidates and call again.

• delete_preset_or_draft answers SCOPE_INSUFFICIENT. Your key lacks the scope for that kind. The error names the scope.

• A tool call fails with a code you don't recognize. Look it up on the errors page, and quote the request_id if you contact support.

Related features

• API: Getting started: create a key, rehearse with a test key, and the rules every call shares

• API: Command-line tool: the same tools as terminal commands

• API: Uploads: the add_assets upload and import modes in detail

• Build presets with the API: list_presets and manage_preset in practice

• Stage Etsy drafts, review them in ListingView, then submit: the drafting loop with a Drafting Agent key

• Publish and reprice live listings: push_listing_live with a Publisher key

• API: Limits & budgets: what tool calls cost and when budgets reset

• API reference: every route, generated live from the API

• Using the ListingView API, MCP server & CLI: the seller guide to keys, presets and Etsy drafts