Pulltrader

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)

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.

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)

Shared inputs (compare_selling_costs, calculate_required_sale_price):

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.

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 installnpm run typecheck   # tsc --noEmitnpm test            # vitestnpm 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_ABUSEwrangler kv namespace create MCP_ABUSE --preview# Paste ids into wrangler.toml [[kv_namespaces]] binding MCP_ABUSEwrangler 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: [email protected]

_{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.}