# PuzzleMaker Pro: AI integration guide

Setup: https://puzzlemakerpro.app/use-with-ai
MCP endpoint: https://puzzlemakerpro.app/mcp
Transport: MCP Streamable HTTP (JSON responses, stateless; no SSE session required).
No API key or account is needed for search, create_puzzle, and get_puzzle.
Connect an OAuth account for exporting, saving, and online assignments.
Availability in a provider directory is separate from this endpoint; see your assistant's custom connector settings.

## Tools
- search_puzzles(query, type?, limit?): find premade activities; returns canonical page and editing URLs.
- create_puzzle(type, title, ...content): build a new seven-day draft; returns id, previewUrl, editUrl, previewImageUrl, expiresAt, warnings, omittedWords.
- get_puzzle(id): retrieve a draft's links, title, warnings, and expiry.
- export_puzzle(id, includeAnswerKey=false): connected account required; returns a PDF download URL valid for one hour. Free: 10 exports/month shared with website usage. Pro: unlimited exports, no watermark; includeAnswerKey requires Pro. Bingo has no answer key. Retries during the same clock hour reuse a completed export.
- save_puzzle(id): connected account required; save to the teacher dashboard. Repeated calls reuse the saved puzzle.
- create_assignment(id): connected Pro account required; returns a student play URL, join code, and teacher results URL. Only call when the teacher asks to assign/distribute. Bingo is not supported. Repeated calls return the existing assignment, including its active status.

## Generation inputs
All input objects reject unknown fields. Type and title are required. Title: 1-100 basic ASCII characters. English letters/basic punctuation only in this integration.
- word-search: words (1-40 unique words, 2-30 English letters each), gridSize (8-30, default 15), difficulty (easy|medium|hard, default medium).
- crossword: wordClues (2-25 objects with word and clue), gridSize (8-30, default 15). Answers contain 2-30 English letters; clues have 1-180 basic ASCII characters.
- bingo: items (24-100 unique terms, up to 40 basic ASCII characters), numCards (1-30, default 1), freeSpace (default true; at least 25 items if false).
- word-scramble: words as above. Every word must have at least two different letters.
- matching: pairs (2-20 objects with left and right; maximum 80/160 basic ASCII characters).
- maze: gridWidth and gridHeight (6-30, default 20), difficulty (easy|medium|hard). Easy halves the requested dimensions, matching the website generator.

The assistant supplies vocabulary/clues. PuzzleMaker Pro does not call a language model or fact-check the educational content. Review content with the teacher. Report every omittedWords entry; increase grid size or revise the content if words did not fit. Do not claim a partial layout includes every requested word.

## Example
User: Make a simple water-cycle word search.
create_puzzle({"type":"word-search","title":"The Water Cycle","words":["WATER","CLOUD","RAIN","VAPOR","RIVER"],"difficulty":"easy"})
Show previewUrl and editUrl. If the user requests a PDF, call export_puzzle with the returned id. Follow the account connection challenge if needed. Return downloadUrl after success.

## OAuth
Protected resource metadata: https://puzzlemakerpro.app/.well-known/oauth-protected-resource
Authorization server metadata: https://puzzlemakerpro.app/.well-known/oauth-authorization-server
Resource/audience: https://puzzlemakerpro.app/mcp
Dynamic client registration: POST /api/ai/oauth/register (client_name, redirect_uris, token_endpoint_auth_method="none").
Authorization code flow: PKCE S256 required; exact registered redirect URI, state, and resource required. HTTPS callbacks or localhost HTTP callbacks only.
Token endpoint: POST /api/ai/oauth/token (form-encoded or JSON). Include resource in code exchange and refresh requests.
Scopes: puzzles:export, puzzles:save, assignments:create.
Access tokens expire after one hour. Refresh tokens rotate on use and expire after 30 days. Never copy browser session cookies or ask the user to paste tokens into chat.
Revocation: POST /api/ai/oauth/revoke (token, client_id). Teachers can revoke from /ai/connections.

## HTTP API
POST /api/ai/puzzles: generation body identical to create_puzzle; JSON Content-Type required.
GET /api/ai/puzzles/{id}: draft, editor state, and preview page count.
GET /api/ai/puzzles/{id}/preview?page=1: SVG preview; page is one-based.
POST /api/ai/puzzles/{id}/export: {"includeAnswerKey":false}; OAuth bearer with puzzles:export.
POST /api/ai/puzzles/{id}/save: OAuth bearer with puzzles:save.
POST /api/ai/puzzles/{id}/assign: OAuth bearer with assignments:create.
GET /api/ai/downloads/{downloadId}: PDF bytes from an authorized export's short-lived download URL.
Errors: 401 connect/reconnect; 403 plan or scope; 404 invalid/expired link; 409 export preparing; 413 request too large; 422 invalid puzzle; 429 quota/rate limit; 503 storage unavailable.

## Privacy and limits
Draft and download URLs are capability links: anyone with the URL can read them. Drafts expire after seven days; downloads expire after one hour. Saved puzzles and assignments follow account retention. Do not send student names or personal information. The MCP server cannot read student results, change billing, or delete saved puzzles.
Generation rate: 20/minute per connected account or anonymous IP. MCP requests: 120/minute per IP. Exports: 30/minute/account. Assignments: 30/hour/account. These abuse limits are separate from plan allowances.
Privacy: https://puzzlemakerpro.app/privacy
Terms: https://puzzlemakerpro.app/terms
Pricing: https://puzzlemakerpro.app/pricing