The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Pulltrader Seller Economics listing page.
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. Seven tools: four back onto Scout'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.
POST /mcp)https://mcp.pulltrader.app/mcpapp.pulltrader/seller-economics2025-06-18 (the client's requested version is echoed when present)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.
| 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 |
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.
| 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.
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).
Settings → Connectors → Add custom connector → URL https://mcp.pulltrader.app/mcp.
Settings → Apps & Connectors → Advanced → enable Developer mode → Create → URL https://mcp.pulltrader.app/mcp.
Add to your MCP client config:
Tested clients: Claude (web/Desktop), ChatGPT developer mode, Cursor, MCP Inspector. We do not claim universal compatibility with every assistant.
Public and read-only. There is no authenticated tier in this release.
| 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.
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.
Current schedule versions are served live at /version.
Deploy and registry submission require explicit approval — see docs/DEPLOYMENT.md and docs/DISTRIBUTION.md. Do not deploy or publish from a development session.
Built and maintained by Pulltrader. Support: support@pulltrader.app
This repository is the public mirror of the Scout 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.