Pulltrader — Trading-Card MCP Server

Identify a card, pull recent sold comps, summarize its market value, chart its price history, and compare what a seller keeps across eBay, Pulltrader, and other card marketplaces — inside your AI assistant.

A public, read-only Model Context Protocol server for trading-card research and selling. Eight tools: a Kapture stolen-card registry check, four back onto Pulltrader's card data (identification, comparable sold sales, market value, price history), three run Pulltrader's deterministic seller-economics engine over a dated, versioned fee schedule.

Market figures are estimates derived from recent sales. Fee math is deterministic — the server computes it and never asks the model to infer fees from prose. eBay figures are clearly labeled estimates.

• Transport: Streamable HTTP (POST /mcp)
• Auth: none (public, read-only)
• Endpoint: https://mcp.pulltrader.app/mcp
• Registry name: app.pulltrader/seller-economics
• Protocol: 2025-06-18 (the client's requested version is echoed when present)

Who it's for

Trading-card sellers, dealers, shops, and collectors who want to know what a card is, what it's worth, and what they'd actually take home selling it — without leaving their assistant.

What it does (and doesn't)

Does	Doesn't
Resolve a prose card description into structured fields	Identify a card from an image (text only)
Return recent comparable sold sales (price + date)	Return listing, affiliate, or per-sale outbound URLs
Summarize market value: median, mean, p10–p90, volatility, confidence	Claim a guaranteed value or give financial advice
Chart price history by day / week / month with a trend	Make any write, order, or account change
Estimate seller fees and net proceeds per selling method	Claim one platform is universally cheapest
Solve for the price needed to hit a target net	Model auction formats (hammer, buyer's premium, consignment)
State its assumptions, data freshness, and limitations	Cover non-card categories or currencies other than USD

Tools

Kapture cert check (data-backed)

check_kapture_cert accepts { "cert": "00123456" } and preserves leading zeros. CLEAN only means no verified stolen report matched. STOLEN includes the Kapture report and a voluntary Pulltrader recovery-form link. The tool never collects personal information, infers possession, or submits a recovery report. The backend holds KAPTURE_API_KEY; no new Worker secret is needed. Recovery handoff is manual until Kapture provides a reporting API. See pulltrader-backend/docs/KAPTURE.md.

Card research (data-backed)

These bridge to the Pulltrader backend. Card data is limited-public: a capped sample of sales, no per-listing or affiliate URLs, and only the catalog reference image.

Each accepts either query (a natural-language description, e.g. "2023 Panini Prizm Victor Wembanyama #136 Silver PSA 10") or item (structured fields: player_athlete, year_manufactured, set_name, card_number, parallel_variety, grader, grade, sport). One of the two is required.

Tool	What it returns
identify_card	Canonical fields (player/athlete, year, set, number, parallel, grader, grade, category) plus a confidence level and which fields resolved. Takes query only. Does not price the card.
search_card_sales	A capped sample of recent comparable sold sales (price + date) plus a market snapshot. Optional limit.
summarize_card_market	Canonical market value: median, mean, p10–p90, volatility, sample size, confidence.
get_card_price_history	A chart-ready time series with a trend. Optional interval: day | week | month.

When eBay has no dated comps, search_card_sales and summarize_card_market fall back to the authoritative vendor price and surface market_value, value_source (TCG Market | CardSightAI | eBay Comps), price_change_7d, price_change_30d, and a single catalog image.

Seller economics (deterministic, no I/O)

Tool	What it returns
compare_selling_costs	Estimated fees and net proceeds for one sale across selling methods, with a per-method fee breakdown, the difference vs the eBay baseline, and the assumptions used. Requires sale_price.
calculate_required_sale_price	The per-item price needed to reach a target take-home (or net profit, when acquisition_cost is given) on a single method. Requires target_net.
explain_selling_method	Plain, structured explanation of how each method owns the listing, fulfills, and charges fees. Derived from the same engine, so it never drifts from compare_selling_costs.

Shared inputs (compare_selling_costs, calculate_required_sale_price):

Field	Type	Default	Notes
currency	enum USD	USD	Only USD supported
quantity	integer	1	Per-order fixed fees applied once
shipping_amount	number	0	Affects eBay's fee base
item_category	enum trading_cards	trading_cards	Only trading cards
seller_plan	free|starter|pro|shop	free	Marketplace payout tier
seller_level	enum	derived from plan	Explicit payout level override
seller_covers_fees	boolean	false	If false, the buyer pays the platform fee
ebay_store_subscription	boolean	false	eBay Store rate (12.35%) vs individual (13.25%)
acquisition_cost	number	—	Switches output to net profit
ebay_fee_percent_override	number	—	Override the estimated eBay FVF % (flat)

Supported methods: ebay, pulltrader_marketplace, pulltrader_fbp, pulltrader_storefront, pulltrader_pos, plus estimated competitor marketplaces tcgplayer, manapool, misprint, fanatics_collect, goldin (off by default — opt in via methods). Competitor figures model fixed-price / Buy Now seller fees only.

Example prompts

• "What is this card: 2023 Bowman Chrome Elly De La Cruz PSA 10?"
• "Show me recent sold comps and the market value for that card."
• "What's the price history on a 2018 Prizm Luka Doncic Silver PSA 10 over the last year?"
• "Compare my estimated proceeds on a $250 graded-card sale."
• "What would I keep on an $80 card on eBay vs Pulltrader?"
• "What do I have to sell it for to clear $200 after fees?"
• "Explain the assumptions behind this payout estimate."

Example response (text summary)

On a $250.00 trading-card sale, estimated seller proceeds by method:
- Sell it yourself on eBay: keep $216.47 (estimated) (fees $33.53, 13.41%)
- Pulltrader marketplace (you ship): keep $235.00 (fees $15.00, 6%)
- Your Pulltrader storefront (you ship): keep $250.00 (fees $0.00, 0%)
For these inputs, Your Pulltrader storefront (you ship) returns about $33.53 more than Sell it yourself on eBay.
Estimate based on fee schedules updated 2026-06-01 (Pulltrader) and 2026-06-27 (eBay, estimated). Estimates only, for trading cards in USD. ...

eBay = 13.25% individual FVF + $0.40 per-order fee (orders over $10). The storefront keeps 100% because Pulltrader has no seller fee on storefront/POS — only the platform fee, paid by the buyer here. The platform fee is always charged on Pulltrader card sales (buyer pays by default).

Connecting

Claude (web / Desktop)

Settings → Connectors → Add custom connector → URL https://mcp.pulltrader.app/mcp.

ChatGPT

Settings → Apps & Connectors → Advanced → enable Developer mode → Create → URL https://mcp.pulltrader.app/mcp.

Cursor / generic

Add to your MCP client config:

{
  "mcpServers": {
    "scout-by-pulltrader": {
      "url": "https://mcp.pulltrader.app/mcp"
    }
  }
}

Tested clients: Claude (web/Desktop), ChatGPT developer mode, Cursor, MCP Inspector. We do not claim universal compatibility with every assistant.

Public access & rate limits

The /mcp endpoint is public and read-only. A separate seller resource is implemented at /seller/mcp; OAuth is provisioned and its signed-in pilot is pending. See Seller MCP.

Limit	Default	Notes
All POST /mcp	60 / IP / min	HTTP 429 + Retry-After. Fail-open if KV is down.
Data tools (identify / comps / market / history)	8 / IP / min, 40 / IP / day	Tool isError RATE_LIMITED. Fail-closed if KV is down.
Data tools global	10,000 / day	Circuit breaker for model + comps spend.
Batch size	5 messages	Larger batches are rejected.

Requires the MCP_ABUSE KV namespace (see wrangler.toml). Tune via PUBLIC_RATE_LIMIT_PER_MIN, DATA_RATE_LIMIT_PER_MIN, DATA_RATE_LIMIT_PER_DAY, DATA_GLOBAL_LIMIT_PER_DAY.

Errors

Input problems come back as a tool result with isError: true and a stable code, not a JSON-RPC error: INVALID_INPUT, NOT_FOUND, RATE_LIMITED, UPSTREAM_ERROR, UPSTREAM_TIMEOUT, DATA_BACKEND_UNAVAILABLE, INTERNAL_ERROR. Unknown methods and malformed envelopes use standard JSON-RPC error codes.

The four card tools require the backend bridge (PULLTRADER_API_BASE + SCOUT_MCP_SECRET). Without it they degrade to DATA_BACKEND_UNAVAILABLE; the three seller-economics tools are pure and always available.

Data sources & fee freshness

• Card data is limited-public and estimate-only: a capped sample of recent sold comps, aggregated by the shared Pulltrader domain engine.
• Pulltrader fees mirror Pulltrader's authoritative internal fee configuration.
• eBay fees are an estimate of published trading-card rates (tiered individual/Store final value fee + order-size-based per-order fee), updated and reviewed on a schedule. See docs/FEE_SCHEDULES.md. Responses warn if a schedule is past its review date.

Current schedule versions are served live at /version.

Limitations

• eBay estimates exclude promoted listings, international fees, buyer-paid sales tax, and the seller's own shipping-label cost.
• Market values are estimates from recent sales, excluding fees, taxes, and shipping.
• Not financial advice; actual proceeds and actual value vary.
• Trading cards / USD only in this release.

Development

npm install
npm run typecheck   # tsc --noEmit
npm test            # vitest
npm run dev         # wrangler dev (local)

Deploy and registry submission require explicit approval — see docs/DEPLOYMENT.md and docs/DISTRIBUTION.md. Do not deploy or publish from a development session.

More

• PRIVACY · SECURITY · TERMS · CHANGELOG
• Fee schedules & update process

Deploy prerequisites

wrangler kv namespace create MCP_ABUSE
wrangler kv namespace create MCP_ABUSE --preview
# Paste ids into wrangler.toml [[kv_namespaces]] binding MCP_ABUSE
wrangler secret put SCOUT_MCP_SECRET

Roadmap

• Image-based card identification.
• Athlete/player profile tools.
• Complete the signed-in seller pilot for /seller/mcp; global per-user quotas remain future work.

---

Built and maintained by Pulltrader. Support: support@pulltrader.app

This repository is the public mirror of the Pulltrader MCP Worker, exported from the Pulltrader monorepo on each release. Issues and questions are welcome here; pull requests are applied upstream. wrangler.toml KV ids are redacted — deploys run from the monorepo.