TCG oracle: calibrated prices & risk, card-loan terms, AI grading, fantasy souls — proven on-chain.
The MCP server provides Conformal TCG risk forecasts and AI card grading, featuring an x402 pay-per-call oracle and on-chain soul agents. It integrates model context, Monte Carlo analysis, and MCP tooling to enable fast, scalable model-context provisioning within narrative trading-card ecosystems.
🛠️ Key Features
Conformal prediction-based risk forecasts for collectible card contexts
AI card grading and evaluation capabilities
x402 pay-per-call oracle for on-demand access
On-chain soul agents for persistent agent behavior
Python-based implementation with FastMCP integration
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).
35+ local compute tools for AI agents — plus a hosted, conformal-calibrated pricing oracle
Run it fully local with zero cloud dependency, or connect to the hosted endpoint at mcp.the-undesirables.com — 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. 23 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.
Quick Install
bash
pip install undesirables-mcp-server
Turn any Undesirable NFT into an MCP-compatible AI agent with 35+ local compute tools.
v1.1.8 adds the FREE card_forecast(card_name | product_id) tool — one call returns the conformal 30-day price forecast plus Safe-Hold & Momentum letter grades and a one-line plain-English read (e.g. "~12% chance it's below $Y in 30 days; Safe-Hold B, Momentum A"). No payment required.
The conformal-calibrated risk forecast is the default model — regime-aware split-conformal bands with honest VaR/CVaR, plus Safe-Hold & Momentum letter grades. Monte Carlo (GBM / Merton Jump-Diffusion) remains available opt-in via model=. Also: corrected license badge and full ecosystem integration.
Key Features:
purchase_undesirables_license_key — Returns an unsigned EVM transaction payload (Ethereum Mainnet, chainId 1) for autonomous agents to mint directly from the Scatter.art contract
verify_soul_initialization — Verifies on chain purchase via public RPC and initializes the cryptographic soul matrix, unlocking all local compute engines
Verified on Glama.ai with a 3.8/5 quality score across 36 tools
Download Ollama. CRITICAL: You cannot just download the app and leave it in your downloads folder. You must double-click the Ollama app to physically run it. You should see a little llama icon in your Mac menu bar or Windows system tray for this server to work.
🛠️ Step 1: Install & Clone
First, open your Terminal or Command Prompt and clone this repository. After cloning, you must activate a "Virtual Environment" (a sandbox folder just for this codebase).
Every single time you want to run this server later, you must open your terminal and make sure your Virtual Environment is activated (venv) first!
If you already downloaded your Soul Workspace from the website:
bash
# Make sure to point to your EXACT soul folder path
python server.py --workspace "/Users/username/Desktop/soul_folder/0420"
🔌 Step 3: Connect Your Chat Front-End
The MCP Server doesn't have a chat window; it runs invisibly in the background of your terminal! To actually talk to your agent, you must connect it to a desktop application like Claude or Cursor.
Claude Desktop Connection
Open the Claude Desktop application on your computer.
Go to Settings > Developer > Edit Config.
Paste this into your config file, making absolutely sure you replace the cwd (Current Working Directory) with your exact folder path:
Restart the Claude Desktop app. You should see a little "Plugin/Hammer" icon telling you that 35+ The Undesirables tools are now available!
🎨 Step 4: Setup Local Image Generation (Optional)
If you want your agent to physically generate memes and illustrations 100% offline natively on your computer, the MCP Server uses the massively powerful 16GB FLUX.1-schnell model.
If you do not complete this step, or if your computer is too weak (< 12GB RAM), the server will automatically fallback and generate memes for you silently via the free Pollinations.ai cloud network.
🍏 Authenticating Apple Silicon (Mac M1/M2/M3/M4)
Apple Silicon specifically uses mflux, which strictly requires a Hugging Face token to bypass Black Forest Labs' legal compliance gate.
Open your Mac terminal, activate your virtual environment, and log in:
bash
cd undesirables-mcp-server
source venv/bin/activate
python -c "import huggingface_hub; huggingface_hub.login()"
Paste your token and press Enter(your clipboard characters will be invisible for security).
🪟 Setup for Windows/Linux GPUs
If your computer uses Nvidia CUDA or AMD DirectML, the diagnostic scanner detects this and logically shifts your engine to an ungated open-weights repository (shuttleai/FLUX.1-schnell).
You do not need to authenticate anything or make an account.
Simply ask your agent to generate a meme in the UI! Your system will natively download the 16GB weights fully offline during the very first execution automatically.
⚠️ Common Idiot-Proof Diagnostics
If your terminal throws red text and halts, check these top 3 reasons:
Error: Ollama connection refused
Your AI's brain is offline! Make sure you physically double-clicked the Ollama.app on your computer. If the little llama icon isn't in your menu bar/taskbar, local inference will fail immediately.
ModuleNotFoundError: no module named fastmcp
You forgot to activate your Virtual Environment. You cannot just launch a fresh terminal and run python server.py. You must navigate to the folder and run source venv/bin/activate (Mac) or venv\Scripts\activate (Windows) first!
Invalid JSON: expected value at line 1
The Python terminal running the MCP Server is communicating in raw machine code (JSON-RPC). You cannot type plain English into that terminal window! Once it turns on, leave it alone. Open Claude Desktop or Cursor to chat with it.
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:
