JotOak MCP – Printable Puzzle Tools for Developers

Connection

Public endpoint. Version 0.1.0 is available as of October 15, 2026. Connect your MCP client using the URL below.

Endpoint URL: https://jotoak.com/mcp
Transport: Streamable HTTP, stateless JSON responses
Authentication: No account or API key; public, read-only catalog
Official Registry: io.github.iyuyoung/jotoak · v0.1.0

Use a client that supports remote Streamable HTTP servers. Initialize the connection, discover the tools, then call a tool with the arguments below. POST is supported at both /mcp and /mcp/; there is no long-running GET event stream or persistent session.

Tools and filters

`search_puzzles`

Search the same prepared word searches, crosswords and mazes that appear in the JotOak library. Results include an exact ID, description, source page, preview and real PDF editions. Results follow the library's stable order; they are not ranked recommendations.

Optional search_puzzles arguments
Argument	Allowed values
`query`	1–100 characters; all words must match a title, description or word list
`kind`	word-search, crossword, maze
`difficulty`	easy, medium, hard; word searches only
`largePrint`	true or false; word searches only
`holiday`	halloween, thanksgiving, christmas; word searches only
`paper`	letter or a4; omit for both editions
`offset` / `limit`	Offset 0–1000, default 0; limit 1–10, default 5

The result contains items, total and nextOffset. Use the returned offset for the next page. A null offset means the end. No matches returns an empty list.

`get_puzzle`

Pass the exact id returned by search and an optional paper. The result adds instructions, printing guidance and the published vocabulary or clues. An unknown ID returns a tool error. Invalid arguments are rejected, including unsupported filters or extra fields.

Unrecorded difficulty, typography or grid dimensions return null rather than an invented label. Crossword and maze difficulty is not inferred. These tools do not generate custom puzzles, search the earlier math archive or return answer placements as text.

Examples

Arguments for a tools/call request, after MCP initialization:

{
  "name": "search_puzzles",
  "arguments": {
    "kind": "word-search",
    "holiday": "christmas",
    "paper": "a4",
    "limit": 3
  }
}

{
  "name": "get_puzzle",
  "arguments": {
    "id": "garden-animals",
    "paper": "letter"
  }
}

Successful tools return validated structuredContent, the same JSON as text for client compatibility, and standard resource_link entries for the PDFs. File metadata includes paper size, MIME type, page count and the published data version.

Files and permissions

Each returned PDF has two pages: the puzzle on page 1 and its matching answer on page 2. Print only page 1 for the solver. Letter and A4 are editions of the same puzzle, with the same underlying data. There is no separate answer PDF.

The source page contains a preview and useful guidance. PDF links point directly to published files; the MCP server does not create temporary downloads or require a visit to an advertising page.

Free for home and direct classroom use. Keep the JotOak source line, and share the original page. Do not resell the files or republish them as a download library. See usage permissions.

Limits and privacy

Requests are limited to 16 KiB and five seconds. Cloudflare rate limits allow approximately 120 requests per network address per minute and 600 shared requests per minute at each Cloudflare location. These are regional protections, not a global quota. A shared school network may share an address limit.

HTTP 429 includes Retry-After: 60. Retry after that interval. HTTP 503 means the service is unavailable; HTTP 504 means a timeout. Avoid unbounded retries. An empty result is not an outage.

Browser requests must use the configured site Origin. Requests without Origin are accepted for server clients. CORS is not authentication. Requests cannot fetch arbitrary URLs, upload files, create accounts or save custom words.

Unlike the browser-only generator, MCP search arguments are processed by a server. Do not send names, student data or private vocabulary. Application logs contain only status and duration; they exclude raw queries, arguments and network addresses. Cloudflare processes network information to serve and protect requests. See MCP privacy details.

Support

Report a connection problem or incorrect puzzle record to [email protected]. Include the tool name, published puzzle ID and HTTP status, without private input or credentials.

For the browser experience, browse printable word searches, crosswords or mazes.