We just shipped the open-source MCP server for YesNoMystery (Lateral Thinking Puzzles / Turtle Soup / Black Stories):
- GitHub: yesnomystery/yes-no-mystery-mcp
- npm:
yes-no-mystery-mcp(and CLI aliaslateral-thinking-puzzles-mcp) - Remote Streamable HTTP:
https://lateralthinkingpuzzles.org/api/mcp - Official MCP Registry:
io.github.yesnomystery/yes-no-mystery-mcp
Here is how we designed one shared TypeScript backend to power both remote Streamable HTTP and local stdio, along with three production bugs we caught before opening it up to MCP clients.
Why Lateral Thinking Puzzles Fit MCP
In a lateral thinking puzzle ("Turtle Soup"), the host gives players a brief, paradoxical scenario. Players ask yes/no questions to reconstruct the hidden backstory until they solve the mystery.
Mapping this loop onto Model Context Protocol (MCP) tools turns any AI client (Claude Desktop, Cursor, VS Code, Claude Code) into either:
- A solo detective: the LLM searches mysteries by language, difficulty, category, or tags, asks yes/no questions step by step, and unlocks clues on a 0–120 mastery scale.
- An interactive host: you pick a puzzle together and ask questions directly inside your editor or chat app.
We kept the tool surface to four focused primitives:
-
ynm_search_puzzles— filter 1,000+ official puzzles and password-free public community (UGC) puzzles across 12 languages (en,zh,zh-TW,ja,ko,de,es,fr,it,pt,ru,th). -
ynm_get_puzzle— fetch a puzzle's scenario, target questions, unlocked clues so far, progress (0–120), and current answer reveal cost. -
ynm_ask_question— ask a yes/no deduction question (yes,no,unknown,partial_ok,irrelevant,needs_rephrase). Supports both stateful Q&A history (default, up to 20 turns cached per puzzle in the CLI wrapper) and stateless standalone evaluation (include_history: false). -
ynm_reveal_solution— reveal the full solution and all clues using the same dynamic pricing as the website: 20/30/40 credits at 0 progress, dropping linearly down to 1 credit at 80+ progress, and 0 credits (free) once progress hits 100.
Search and detail endpoints strip solution and locked clues completely—there is no accidental spoiler in tool responses.
Architecture: One Backend Service for Two Transports
Rather than duplicating puzzle resolution, quota accounting, or AI prompting in a separate daemon, all logic lives inside our Next.js App Router codebase (src/lib/mcp/*) and exposes two entrypoints over the same service layer:
Remote clients ──▶ POST/GET/DELETE /api/mcp (Streamable HTTP via @modelcontextprotocol/server) Local stdio ──▶ npx -y yes-no-mystery-mcp └─ GET /api/mcp/puzzles └─ POST /api/mcp/ask └─ POST /api/mcp/reveal The yes-no-mystery-mcp npm package stays under 10 KB compressed: it validates schemas with zod, keeps optional local Q&A history in memory for stdio sessions, and talks to those thin JSON routes with explicit timeouts and X-MCP-Client-Id headers.
Three Production Gotchas We Ran Into
1. Cookie Isolation & Zero-Token Anti-Abuse Preflight
On our website, logged-in users spend account credits and browser users have SameSite cookies. If /api/mcp/* reused the same getOptionalAuth helper as browser routes, a third-party page or misconfigured client making cross-origin calls could burn a logged-in user's paid credits.
Fix:
-
/api/mcp/*ignores browserCookieheaders completely and never setsAccess-Control-Allow-Credentials. - Instead, the server derives an isolated
mcp_<24hex>anonymous actor ID via HMAC-SHA256 from the trusted request IP fingerprint andX-MCP-Client-Id. - Before touching any LLM provider, a lightweight Postgres check verifies both credit balance and our existing 1-hour / 24-hour IP+UA trial rate limits. Rate-limited or exhausted callers get a clean
402/429JSON response and burn 0 AI tokens.
2. HTTP 301 Silently Turns POST into GET
Our reverse proxy enforces canonical domain redirects (www.lateralthinkingpuzzles.org -> 301 -> lateralthinkingpuzzles.org).
That works invisibly for browser GET page views. For MCP over HTTP, standard fetch() converts a POST request into a GET when it follows a 301 redirect and drops the JSON body—breaking POST /api/mcp and POST /api/mcp/ask.
Testing against the live edge caught this right before npm publish. Aligning DEFAULT_API_BASE_URL, server.json (remotes[0].url), and client docs to the apex URL https://lateralthinkingpuzzles.org/api/mcp removed the redirect completely.
3. Official MCP Registry Namespace & Schema Checks
When publishing io.github.yesnomystery/yes-no-mystery-mcp to the Official MCP Registry (registry.modelcontextprotocol.io), two constraints tripped us up at first:
- The
2025-12-11server.schema.jsonenforcesdescriptionmaxLength: 100(while our initial draft was 129 chars). - Interactive
mcp-publisher login githubdevice OAuth cannot read organization memberships (#1468), so publishing under a GitHub Organization namespace (io.github.yesnomystery/*) requires GitHub Actions OIDC (./mcp-publisher login github-oidc) withid-token: write.
Adding Sigstore verification of mcp-publisher inside a minimal workflow let us publish directly from the org repo with zero long-lived tokens.
Try It in 10 Seconds
Option A: Remote Streamable HTTP (Zero Install)
{ "mcpServers": { "yes-no-mystery": { "url": "https://lateralthinkingpuzzles.org/api/mcp" } } } Option B: Local npx (stdio)
{ "mcpServers": { "yes-no-mystery": { "command": "npx", "args": ["-y", "yes-no-mystery-mcp"] } } } Each anonymous client starts with 50 free trial credits (25 AI questions), and reaching 100/120 progress unlocks the full solution for free.
Play on the web anytime in English, 简体中文, or 日本語, or check out the source on GitHub.