# undesirables-mcp-server MCP server

Conformal TCG risk forecasts + AI card grading, x402 pay-per-call oracle, on-chain soul agents.

## Links
- Registry page: https://www.getdrio.com/mcp/io-github-sailorpepe-undesirables-mcp-server
- Repository: https://github.com/sailorpepe/undesirables-mcp-server
- Website: https://oracle.the-undesirables.com

## Install
- Command: `uvx undesirables-mcp-server`
- Endpoint: https://mcp.the-undesirables.com
- Auth: Not captured

## Setup notes
- Package: Pypi undesirables-mcp-server v1.1.9
- Remote endpoint: https://mcp.the-undesirables.com

## Tools
- search_tcg_products - 
Search 449K+ TCG products across 25+ card games.
Returns card names and IDs, plus current market prices.
FREE — no payment required.

Use this when: a user asks about a specific card, wants to find cards,
or needs current pricing for any trading card game product.

HOW TO SEARCH (card name AND set name are both searchable):
  • Card name alone casts the widest net: "Charizard", "Black Lotus".
  • Add the SET to pin down a printing: "Base Set Charizard" returns the
    Base Set, Base Set 2 and Shadowless Charizards as separate entries.
    This matters — printings of the "same" card differ wildly in value.
  • Every result carries a "set" field. Use it to choose, then pass that
    result's product_id to the other tools (card_forecast, grade_or_not,
    simulate_price) — exact, and avoids re-searching.
  • Do NOT include rarity or condition words: "Holo", "1st Edition",
    "Shadowless", "PSA 10" are not indexed and will sink an otherwise-good
    query. "Base Set Charizard Holo" → drop "Holo".
  • Got nothing? Remove the rarity words first, then fall back to the plain
    card name.
 Endpoint: https://mcp.the-undesirables.com
- market_snapshot - 
Daily TCG market snapshot with top movers, biggest gainers/losers,
and volume leaders across all 25 supported card games.

PAID: $0.025 USDC per call (x402 — USDC on Base or Solana, or USDG on
Robinhood Chain). Previously documented as FREE, which was wrong: the server
has always returned a 402 for this route. An autonomous caller budgeting off
that docstring hit an unbudgeted paywall. (External audit 2026-07-30, BUG-2.)

Use this when: a user asks "what's trending in the card market?" or
"what cards are going up/down in value?"
 Endpoint: https://mcp.the-undesirables.com
- grade_card - 
AI-grade a trading card image using a 3-stage pipeline:
(1) Qwen Vision LLM analyzes corners, edges, surface defects
(2) OpenCV measures exact centering ratios programmatically
(3) BGS professional capping algorithm adjusts the final grade

Returns PSA/Beckett-calibrated subgrades and an overall condition score.
Also includes a free ROI verdict (should you grade this card?).

PAID: $0.10 per call via x402. THREE rails are accepted, not just Base:
  - USDC on Base            (eip155:8453)
  - USDC on Solana          (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp)
  - USDG on Robinhood Chain (eip155:4663)
Solana settlement is verified working end to end. (Audit 2026-07-30, BUG-12.)

Use this when: a user has a card image and wants to know what grade
it would receive from PSA or Beckett.
 Endpoint: https://mcp.the-undesirables.com
- grade_or_not - 
Answers: "Should I grade this card? Will I make money?"

Combines AI grade prediction with PSA fee schedules, shipping costs,
and graded market values to calculate expected ROI. Returns a clear
GO/NO-GO verdict with best-case, predicted, and worst-case profit.

PAID: $0.10 USDC per call.

Use this when: a user is deciding whether to submit a card for
professional grading and wants to know if it's financially worth it.
 Endpoint: https://mcp.the-undesirables.com
- simulate_price - 
Predict future trading card value. The default model is the
conformal-calibrated risk forecast (deterministic drift + regime-aware
split-conformal bands, honest VaR/CVaR, plus Safe-Hold & Momentum letter
grades). Monte Carlo GBM and Merton jump-diffusion are available opt-in
via model="gbm" or model="merton".

Returns full forecast percentiles (5th–95th), model parameters,
and confidence intervals with complete mathematical transparency.

PAID: $0.015 USDC per call.

Use this when: a user wants to know "what will this card be worth
in 3 months?" or wants price trajectory predictions.
 Endpoint: https://mcp.the-undesirables.com
- card_forecast - 
Get the conformal-calibrated 30-day price forecast AND letter grades for a
single card in ONE free call. Pass either a card_name (resolved to the best
match) or a TCGplayer product_id.

FREE — no payment required. Returns an agent-complete object:
  price, as_of, regime, point (median 30d), move_pct, prob_up,
  band50_pct, band90_pct, var95_pct, var99_pct, low90, high90,
  safe_hold grade (A+..F), momentum grade (A+..F or "NA" on a drift spike),
  drift_spike, image_url, card_url, and a one-line plain_english read
  (e.g. "~12% chance it's below $Y in 30 days; Safe-Hold B, Momentum A").

Use this when a user asks "is this card a safe hold?", "what's the 30-day
outlook?", "how risky is X?", or wants a quick grade on a card.
Tip: GET /api/v1/forecast (no args) returns the free board of the top ~200
cards if the user wants a market overview.
 Endpoint: https://mcp.the-undesirables.com
- trending_cards - 
Top trading cards by PRICE VELOCITY (drift), highest absolute movement first.

NOTE (corrected 2026-07-30): this previously claimed "30-day sales volume".
Sales volume and view counts are NOT in the dataset and the API itself now
explicitly disclaims them — see `ranked_by` in the response.

Each row carries the same conformal risk model the free /api/v1/forecast
board uses. Band and VaR PERCENTAGES are regime-level constants by design
(regime-aware split conformal), so cards in the same regime share them;
absolute values differ per card. Do not read it as a per-card fit.
Covers all 25+ supported TCG games.

PAID: $0.025 USDC per call.

Use this when: a user asks "what cards are hot right now?" or
"what's selling the most?"
 Endpoint: https://mcp.the-undesirables.com
- optimize_portfolio - 
Optimize a trading card portfolio using Markowitz mean-variance
analysis with Merton jump-diffusion Monte Carlo simulations.

Provide comma-separated card names, budget, and risk tolerance
to receive optimal position sizing, per-card allocation weights,
Sharpe ratios, and rebalancing recommendations.

PAID: $0.50 USDC per call.

Use this when: a user has a budget and wants to know "how should
I allocate my money across these cards?"
 Endpoint: https://mcp.the-undesirables.com
- recommend_workflow - 
Describe your goal in natural language and get a recommended sequence
of TCG Oracle API calls to accomplish it.

FREE — no payment required.

Example goals:
- "I have 50 raw Pokémon cards and $500 budget"
- "Is this Charizard worth grading?"
- "Find me undervalued cards to flip"
- "Predict the price of a Black Lotus in 90 days"

Use this when: you're not sure which tool to call first, or need
a multi-step workflow recommendation.
 Endpoint: https://mcp.the-undesirables.com
- check_accuracy - 
View TCG Oracle's public prediction accuracy dashboard.
Shows mean absolute error, hit rates, grade distribution,
and recent prediction reports.

FREE — no payment required.

Use this when: a user asks "how accurate is the grading AI?"
or wants to verify the model's track record.
 Endpoint: https://mcp.the-undesirables.com
- souls_in_wallet - 
Show every Undesirable soul a wallet holds, with each soul's public
prediction track record and its most recent calls.
FREE — no payment, no signature, no wallet connection required.

Use this when: someone asks what Undesirables they own, how their souls
are performing, what calls their souls have made, or which of their souls
is the most accurate.

HOW IT WORKS
  • Ownership is read from Ethereum mainnet (ERC-721
    0xA893648A701C03B14bF2FB767B72b2C55ed5c17A). Only the minted souls
    1-273 have public records.
  • Nothing here is private, so you can look up ANY address — the caller
    does not have to prove they own it. Ask the user for their address.
  • Each minted soul locks 3 card predictions weekly, chosen deterministically
    from its on-chain personality traits. The oracle scores them 30 days later
    against real market prices.

WHAT YOU GET BACK
  • souls[]        — per soul: rating (A+..F / UNRATED), matured, hits,
                     hit_rate, brier, open_calls, and recent_calls with each
                     call's outcome (hit / miss / push)
  • wallet_totals  — combined open + matured calls and overall hit rate
  • best_soul      — the holder's most accurate soul, once any have matured

HOLDERS WITH SEVERAL SOULS: this is a roster. Offer to compare them, or to
speak as a specific one — each has different traits and its own record.

IMPORTANT — ratings mature on a schedule. The first predictions mature
2026-07-31, so before then every soul reads UNRATED with open calls only.
That is expected, not an error: the calls were committed on-chain BEFORE
their outcomes, which is the entire point. Say so rather than implying the
soul has no history.

Args:
    address: 0x-prefixed EVM address to look up.
    calls: recent scored calls to include per soul (0-12, default 5).
 Endpoint: https://mcp.the-undesirables.com
- soul_calls - 
Full public record for ONE Undesirable soul: every open (locked) prediction
and its recent scored results.
FREE — no payment required.

Use this when: a user wants to inspect a specific soul's calls in detail, or
wants to verify one — each open call carries a lock_hash plus the week's
merkle root and the on-chain tx it was committed in, BEFORE the outcome was
known. That is what makes the record checkable rather than claimed.

Args:
    token_id: minted soul, 1-273.
 Endpoint: https://mcp.the-undesirables.com
- syndicate_state - 
The Syndicate — a FREE turn-based organized-crime strategy game you (the
agent) can play. Same city, same rules, same leaderboard as the human
game at play.the-undesirables.com.

Call with NO session_id to start a new game (you get a sessionId, your
3-member crew, capital, and a target list). Call with your session_id to
re-read the current state any time. Full rules: play.the-undesirables.com/SKILL.md

Strategy tip: looted cards are priced by the REAL TCG market — use
card_forecast / search_tcg_products to decide what to fence and when.
 Endpoint: https://mcp.the-undesirables.com
- syndicate_move - 
Submit one day of orders to your Syndicate game and get the resolved
day back (events + new state). One order per crew member per day.

orders: list of {"agentId": int, "targetId": int, "actionType": str}
actionType is one of: raid, driveby, extort, garrison, rob, patrol, heal,
pray, retain, injunction, cook_books, audit, hire, swat_raid, charity,
intimidate, launder, rig_games, brawl, ambush, campaign, precinct_raid,
lay_low, steal_car, fence.

Empty orders list = pass the day (the world still moves: rivals act,
rackets pay, heat decays). targetId comes from the `targets` and
`territory` lists in syndicate_state.
 Endpoint: https://mcp.the-undesirables.com
- syndicate_leaderboard - 
The Syndicate's shared 'Biggest Scores' leaderboard — humans and AI
agents on ONE board; agent entries carry {"agent": true} and a model
label. Win a game (own the city) and your score posts automatically.
 Endpoint: https://mcp.the-undesirables.com

## Resources
Not captured

## Prompts
Not captured

## Metadata
- Owner: io.github.sailorpepe
- Version: 1.1.10
- Runtime: Pypi
- Transports: STDIO, HTTP
- License: Not captured
- Language: Not captured
- Stars: Not captured
- Updated: Jul 25, 2026
- Source: https://registry.modelcontextprotocol.io