The Undesirables TCG Oracle

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.*

Website · Docs · PyPI · 𝕏

---

🔌 Connect over MCP — one URL, no install

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. 25 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:

{

"mcpServers": { "tcg-oracle": { "url": "https://mcp.the-undesirables.com" } } }

Tools: search_tcg_products, market_snapshot, simulate_price, card_forecast, trending_cards, optimize_portfolio, recommend_workflow, oracle_scorecard.

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)

v1.x shipped both surfaces under one command; v2 separates them so each server has one job. The hosted endpoint is unchanged.

Quick Install

pip install undesirables-mcp-server

undesirables-mcp # the TCG Oracle over stdio (25 tools, no keys) — default undesirables-agent-kit # the local 34-tool agent kit

Claude Desktop / Cursor / Zed — add the oracle as a stdio server:

{ "mcpServers": { "undesirables-oracle": { "command": "uvx", "args": ["undesirables-mcp-server"] } } }

Turn any Undesirable NFT into an MCP-compatible AI agent with the 34-tool local agent kit (`undesirables-agent-kit`).

---

Table of Contents

• What It Does
• What's New
• The Local Agent Kit
• Technical Architecture (agent kit)
• Agent Framework Integration
• LitVM TCG Oracle
• Ecosystem
• License & Commercial Use

---

What It Does

The TCG Oracle — undesirables-mcp (default), 25 tools, no keys

The same 25 tools the hosted endpoint serves, over stdio. Every tool answers directly: pay-per-call is paused since 2026-10-02, so nothing asks for payment (the x402 rail stays installed and can be switched back on).

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 | | 🧾 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).

🛑 Prerequisites

1. [Python](https://www.python.org/downloads/) 3.10 or higher.
2. [Ollama](https://ollama.com/) — download it *and run it*. The llama icon must be in your menu bar / taskbar, or local inference fails immediately.
3. A soul workspace folder downloaded from the-undesirables.com (for example soul_folder/XXXX).

🛠️ Install

pip install undesirables-mcp-server

Or, to hack on it:

git clone https://github.com/sailorpepe/undesirables-mcp-server.git

cd undesirables-mcp-server python3 -m venv venv && source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt

🚀 Boot

# point --workspace at your EXACT soul folder

undesirables-agent-kit --workspace "/Users/you/Desktop/soul_folder/XXXX"

(From a clone: python server.py --workspace ".../soul_folder/XXXX".) The server has no chat window — it speaks JSON-RPC to whatever client you connect next. Don't type into that terminal.

🔌 Connect Claude Desktop

Settings → Developer → Edit Config, then:

{

"mcpServers": { "undesirables-agent-kit": { "command": "undesirables-agent-kit", "args": ["--workspace", "/Users/you/Desktop/soul_folder/XXXX"] } } }

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.
• **Modu