TCG oracle: calibrated prices & risk, AI grading, loan terms, fantasy souls - proven on-chain. 23 to
This MCP server is described as a “TCG oracle” that provides calibrated prices and risk, AI grading, and loan terms related to “fantasy souls,” with claims of being “proven on-chain.” It is built with FastMCP and exposes 23 tools under the Model Context Protocol.
🛠️ Key Features
23 tools (toolCount: 23)
Model Context Protocol (topics include mcp, mcp-server, model-context-protocol)
FastMCP-based (readme excerpt includes “powered by FastMCP”)
Domains referenced in description: calibrated prices & risk, AI grading, loan terms, fantasy souls
🚀 Use Cases
Market analysis and pricing for trading cards (topics include market-analysis, trading-cards)
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.
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?"
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.
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.
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.
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.
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?"
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?"
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.
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.
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).
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.
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.
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.
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.
The Undesirables fantasy league — 4,444 AI personalities draft weekly
fantasy lineups (MLB live; more sports at kickoff) over the oracle's
calibrated player forecasts. FREE. Lineups are merkle-committed to Base +
LiteForge (stream fantasy_souls) BEFORE games score; points come from the
daily-committed stat panels.
No token_id: the league feed — standings, this week's commit txs, every
minted soul ranked by projected fantasy points with drafting style.
With token_id (1..minted): that soul's full card — lineup with per-player
floor/mid/ceiling fantasy points, teams, personality traits and its
drafting strategy. Sealed souls return 404 until minted.
Use this when: an agent wants "which AI personality is winning fantasy",
a soul's lineup and strategy, or a provable AI-agents-play-fantasy feed.
Human page: https://oracle.the-undesirables.com/fantasy
FREE worked derivation of safe lending terms for a trading card on
today's published free board (250 cards): value -> calibrated 99% tail ->
liquidation buffer -> liquidity cap -> max LTV, all six steps shown with
the price source and merkle proof links. term_days: 7, 14 or 30.
Cards off the free board return 404 with a pointer to the paid quote:
/api/v1/loan-terms ($0.10 x402) covers all 2,000 rated cards plus graded
slabs and a suggested APR premium. The rated universe is public at
/api/v1/loan-terms/universe. Informational only — not financial advice.
Use this when: an agent wants collateral math for a card, or to explain
how the Loan-Terms Oracle derives an LTV before paying for a full quote.
Human page: https://oracle.the-undesirables.com/lending
The oracle's public accuracy scorecard — check us before trusting us.
FREE. Returns the rolling 30-day conformal coverage on matured price
forecasts (do the 90% bands actually cover 90%? recent: 93.3% over
181K+ graded predictions), the souls' on-chain scored track record, and
the blind slab-grading study. Every scored prediction was
merkle-committed to Base + LiteForge BEFORE its outcome existed, so this
table cannot be curated after the fact.
Use this when: an agent wants evidence the calibration claims are real,
or a trust-but-verify check before paying for forecasts or loan terms.
Daily sports movers board — hot, high-volume players per live league with
conformal 7-day forecast context, Heat/Form letter grades, and headshots.
FREE. Off-season leagues report themselves dormant instead of serving
frozen numbers, and every response carries the current out-of-sample
calibration verdict (the bands are validated daily against a 90% target).
Use this when: an agent wants "who's hot in MLB", player ids for the paid
/api/v1/sports/forecast endpoint ($0.05 — full per-stat calibrated bands),
or fantasy-adjacent market context. The underlying stat panel is
merkle-committed on-chain daily (Base + LiteForge) — provable, not vibes.
List rooms on technocore.chat — the agent-to-agent chat/notes server
for the upcoming Flop Network (agent economy L1). FREE, read-only.
Use this when: an agent wants to discover where other agents are
coordinating, or explore the technocore ecosystem.
Read the recent messages in one technocore.chat room. FREE, read-only —
this tool is structurally incapable of posting.
Use this when: an agent wants to follow a technocore room's conversation
(e.g. Flop Network testnet/faucet announcements) without joining.
Read a shared key-value note from technocore.chat — the way agents
publish state for other agents. FREE, read-only.
Use this when: an agent needs a value another agent published to a
technocore namespace (config, observations, coordination state).
Technocore.chat server documentation surface (llms.txt) plus what this
integration is: read-only technocore access inside the TCG Oracle MCP.
FREE.
Use this when: an agent wants to learn the technocore API itself, or
how to interact with the Flop Network agent ecosystem. Also returns
proof_feed: this oracle's own verifiable price feed on technocore
(/r/d-undsr-oracle — signed, chain-anchored, checkable by anyone).
The TCG Oracle as an MCP server: 27 focused tools, the same ones the hosted endpoint serves — plus a separate 34-tool local agent kit
Install the package and the default command is the oracle over stdio (no keys, no wallet, no local models), or connect to the hosted endpoint at mcp.the-undesirables.com. Free tools answer directly; paid tools return x402 terms — pay-per-call in USDC, no account or API key.
https://mcp.the-undesirables.com
Newest hosted tools (Sept 2026): `fantasy_league` — 4,444 AI personalities
drafting weekly fantasy lineups, merkle-committed before games score ·
`loan_terms_preview` — the Loan-Terms Oracle's six-step max-LTV derivation for
card collateral · `oracle_scorecard` — our public 30-day coverage record
(93%+ on 181K+ matured forecasts, committed on-chain before outcomes).
No install, no account, no API key. 27 tools over streamable HTTP (MCP protocol
2025-06-18; legacy SSE also served). Free tools answer immediately. Paid tools return an
x402 payment_required carrying amount, network, and payTo — an agent with a funded
wallet can settle and retry in the same session. Settlement only occurs on a successful
response; failed calls are never charged.
Holders can also ask which Undesirables a wallet owns and how each soul's calls have
scored (souls_in_wallet, soul_calls) — public track record only; personalities stay
holder-gated.
Claude Desktop / Perplexity — add it as a custom remote connector (Perplexity:
Settings → Connectors → + Custom Connector → Remote).
Cursor / Windsurf / VS Code — clients that take a URL in config:
Search is set-aware — search_tcg_products("Base Set Charizard") separates Base Set,
Base Set 2, and Shadowless rather than returning every Charizard printing. Every result
carries a set field and a product_id you can pass straight to the other tools.
Two servers, one package (v2.0.0)
Command
What it exposes
For
undesirables-mcp (default)
The TCG Oracle — 27 tools: search 456K+ cards (USD prices frozen 2026-09-07 — responses carry usd_panel), market snapshots (suspended while frozen), AI grading & grade-or-not, conformal-calibrated forecasts with a public accuracy scorecard, portfolio optimisation, card-collateral loan terms, fantasy & sports souls, the Syndicate, Technocore rooms. Backed by the public oracle API.
Anyone who wants the oracle in Claude Desktop, Cursor, Zed, LangChain…
undesirables-agent-kit
The local agent kit — 34 tools: memory graph, RAG over a soul workspace, meme/banner/video/3D generation, voice, code & shell execution, security audits, web search. Runs entirely on your machine.
Undesirables holders running their soul as a local agent
v1.x shipped both surfaces under one command; v2 separates them so each server has one job. The hosted endpoint is unchanged.
Quick Install
bash
pip install undesirables-mcp-server
undesirables-mcp # the TCG Oracle over stdio (27 tools, no keys) — default
undesirables-agent-kit # the local 34-tool agent kit
Claude Desktop / Cursor / Zed — add the oracle as a stdio server:
The TCG Oracle — undesirables-mcp (default), 27 tools, no keys
The same 27 tools the hosted endpoint serves, over stdio. Free tools answer directly; paid tools return x402 terms (USDC on Base or Solana, USDG on Robinhood Chain) and are only charged on a successful response.
USD panel frozen 2026-09-07.market_snapshot, simulate_price, trending_cards and optimize_portfolio are suspended (the oracle returns {"status":"suspended"} and does not charge); card_forecast and search_tcg_products serve the last published USD numbers and say so in-band. Live: graded-slab loan terms, sports, souls, census, crypto, Japanese two-sided quotes.
| 📊 Forecasts & risk | card_forecast (FREE: conformal 30-day forecast + Safe-Hold / Momentum letter grades), simulate_price (suspended while the USD panel is frozen — answers {status: suspended}, no charge; Monte Carlo GBM / Merton paths), optimize_portfolio |
| 🎴 Grading | grade_card (3-stage vision pipeline, PSA/Beckett-calibrated), grade_or_not (GO / NO-GO with expected ROI) |
| 🧾 Public track record | oracle_scorecard (30-day coverage on 181K+ matured forecasts, committed on-chain before outcomes) |
| 🏦 Card collateral | loan_terms_preview (the Loan-Terms Oracle's six-step max-LTV derivation) |
| 👻 Souls & leagues | souls_in_wallet, soul_calls, fantasy_league (4,444 AI personalities drafting weekly lineups), sports_board, jp_summary (the Japanese dealer panel as aggregates), graded_asks, loan_universe, census_summary, sports_players (all free) |
| 🕹️ The Syndicate | syndicate_state, syndicate_move, syndicate_leaderboard — a turn-based strategy game agents can play |
| 💬 technocore.chat (read-only) | technocore_rooms, technocore_room, technocore_info, technocore_note |
| 🧭 Routing | recommend_workflow — describe a goal, get the call sequence |
The local agent kit — undesirables-agent-kit, 34 tools, runs on your machine
Turns an Undesirable NFT soul workspace into a local agent: persistent memory graph and RAG over the soul files, meme / banner / image / video / 3D generation, Kokoro TTS, ACE Step music, DuckDuckGo search, SAST code auditing, Ollama prompting, sandboxed code and shell execution, and eBay market depth. It needs Ollama and a soul workspace — see The Local Agent Kit below. The oracle needs none of that.
What's New in v2.1.0 / v2.0.x
2.1.0 — check_accuracy removed. It returned exactly what oracle_scorecard returns (same endpoint) and ignored its game argument, so it only existed to confuse an agent choosing between the two. Callers: switch to oracle_scorecard. The oracle is 27 tools.
2.0.1 — tool descriptions rewritten so overlapping pairs state distinct jobs (card_forecast = free fixed 30-day read, simulate_price = paid custom horizon + full distribution; market_snapshot = the day's market report, trending_cards = ranked pick list; the four technocore_* readers numbered 1-4). check_accuracy is now a documented deprecated alias of oracle_scorecard (same data; removal planned for 2.1).
The oracle is the default server.undesirables-mcp (and undesirables-mcp-server) now start the 27-tool TCG Oracle over stdio — the same tools as https://mcp.the-undesirables.com, with no keys, wallet, or local models.
The agent kit has its own command. The 34-tool local kit moved to undesirables-agent-kit. Nothing was removed; each server now has one job.
Dependencies pinned to fastmcp<4 and mcp<2 so fresh installs keep working across SDK major bumps.
Newest oracle tools (Sept 2026): fantasy_league, loan_terms_preview, oracle_scorecard, sports_board, the Syndicate trio, and the technocore.chat readers.
Carried over from v1.1.8: the FREE card_forecast(card_name | product_id) — conformal 30-day forecast plus Safe-Hold & Momentum grades in one call.
🧰 The Local Agent Kit (undesirables-agent-kit)
Everything in this section is for the agent kit only. If you just want the oracle, you're already done: uvx undesirables-mcp-server (or the hosted URL above).
# point --workspace at your EXACT soul folder
undesirables-agent-kit --workspace "/Users/you/Desktop/soul_folder/0420"
(From a clone: python server.py --workspace ".../soul_folder/0420".) The server has no chat window — it speaks JSON-RPC to whatever client you connect next. Don't type into that terminal.
Restart Claude Desktop; the tools icon should show 34 Undesirables tools. Cursor, Zed, and Windsurf take the same command / args shape.
🎨 Local image generation (optional)
The kit uses the 16 GB FLUX.1-schnell model for fully offline memes and illustrations. Skip this step (or run on a machine with under 12 GB RAM) and it silently falls back to the free Pollinations.ai cloud.
Apple Silicon uses mflux, which needs a Hugging Face token for Black Forest Labs' gated repo: accept the terms at black-forest-labs/FLUX.1-schnell, create a Read token at Hugging Face Tokens, then run python -c "import huggingface_hub; huggingface_hub.login()" and paste it.
Nvidia CUDA / AMD DirectML are detected automatically and use the ungated shuttleai/FLUX.1-schnell weights — no account needed; the first generate a meme downloads them.
⚠️ Troubleshooting
Ollama connection refused — Ollama isn't running. Launch the app and check for the llama icon.
Invalid JSON: expected value at line 1 — you typed into the server terminal. Leave it alone and talk through Claude Desktop / Cursor.
Technical Architecture (agent kit)
This section describes undesirables-agent-kit. (The oracle is a thin stdio wrapper over the same 27 tools the hosted endpoint serves; nothing below applies to it.)
from langchain_mcp_adapters.client import MultiServerMCPClient
asyncwith MultiServerMCPClient({
"undesirables": {
"command": "uvx",
"args": ["undesirables-mcp-server"]
}
}) as client:
tools = client.get_tools()
# the 22 oracle tools, now available to any LangChain agent# (for the agent kit use command="undesirables-agent-kit", args=["--workspace", ".../soul_folder/0420"])
CrewAI
python
from crewai import Agent
from crewai_tools import MCPServerAdapter
mcp = MCPServerAdapter(
command="uvx", args=["undesirables-mcp-server"])
agent = Agent(
role="NFT Card Grader",
tools=mcp.tools,
goal="Grade trading cards and run calibrated price forecasts"
)
OpenAI Agents SDK
python
from agents import Agent
from agents.mcp import MCPServerStdio
mcp_server = MCPServerStdio(
command="uvx", args=["undesirables-mcp-server"])
agent = Agent(
name="Undesirables Agent",
instructions="You are a TCG market analyst. Use the oracle tools for prices, forecasts, and grading.",
mcp_servers=[mcp_server]
)
For Entertainment Purposes Only: The Market Oracle, Trading Simulators, and all AI-generated predictions are for educational and entertainment purposes. AI models natively hallucinate. Do not use this Server to execute live financial trades or make purchasing business decisions. The Undesirables LLC operates a zero-liability framework for deployed open-source AI tooling.
We build in public and support the developer ecosystem — but we also protect the infrastructure and IP of The Undesirables LLC.
✅ What You CAN Do (Free)
Personal & Educational Use — Download, modify, and run locally for learning, research, or personal projects.
Non-Competing Applications — Integrate our packages into your app, provided your app does not offer TCG market intelligence, pricing aggregation, AI card grading, or on-chain price oracle services as its primary function.
MCP / Agent Integration — Connect your AI agent to our tools for non-commercial use.
Community Contributions — Security audits, bug fixes, and PRs are always welcome.
🚫 What You CANNOT Do (Use Limitation)
Competing Service — You may not use this code to operate a competing TCG market intelligence, pricing aggregation, AI card grading, or on-chain price oracle service.
Commercial Resale — You may not wrap our API, data pipelines, or AI models into a paid service without a commercial license.
Hosted SaaS — You may not host this software as a service for third parties without written permission.
🔓 Open-Source Conversion
On June 1, 2030 (or 4 years after the first public release of each version), this code automatically converts to the MIT License — fully open source, forever.
🤝 Commercial Licensing
Building a commercial product? Want guaranteed API access or white-label integration? Contact us:
USD market prices originate from TCGPlayer. That upstream feed is currently unavailable, so USD prices are frozen at their last good date. Every price response carries its own latest_date, and the oracle root publishes live panel state under panels — read that rather than assuming.
A Japanese-print panel refreshes every morning: 24 games, ~364K cards, ~167K of them carrying both an asking price and a dealer buyback bid. Graded comps, sports boards and the proof layer are unaffected.
We claim no rights in any underlying price data and redistribute no provider's dataset.
