Sudokumax

npx add-mcp 'https://sudokumax.com/api/mcp'

On this page

Set up with your assistant

A ready-made prompt takes you through connecting, testing and using the tools.

Open the setup prompt in Cursor

Cursor opens a new prompt for you to review. Your agent can help configure the server; you add your API key in MCP settings.

Open setup in Cursor ↗

Requires the Cursor app. Opening the prompt does not install or run anything automatically.

Create your free API key →

No API key or account details are included in the prompt.

Read the setup prompt

Help me set up and use the Sudokumax MCP server in my MCP-compatible client.

Documentation: https://sudokumax.com/developers/mcp
Server: https://sudokumax.com/api/mcp
Transport: Streamable HTTP (stateless JSON responses, no SSE subscription).
Authentication: Authorization: Bearer YOUR_API_KEY on every request.
Create a free account and API key at https://sudokumax.com/developers/keys.

1. Check which client I am using and whether it supports remote MCP with a custom Authorization header. Explain the configuration changes before applying them. Use the client's secure settings for my key; never ask me to paste it into this conversation or put it in a URL, source control, or public code.
2. For Cursor, configure a server named sudokumax in MCP settings with the URL and Authorization header above. For Claude, use a custom connector and its Request headers settings if available on my account. ChatGPT's direct authenticated MCP connection requires OAuth, which Sudokumax does not currently provide: do not claim that a Bearer API key can connect it. Offer a compatible client instead. Cloud clients cannot reach a localhost server.
3. Initialize the connection and list the available tools. Do not say setup is complete until a real tool request succeeds. If the hosted endpoint is unavailable, report that rather than inventing a result.
4. First test: call generate_puzzles with {"count":1,"difficulty":"beginner"}. Explain the puzzle grid, solution, analysis and attribution in the returned result.
5. Explain the available tools: generate_puzzles, check_uniqueness, analyze_difficulty, validate_progress, get_hint, publish_puzzles, export_worksheets and create_worksheet_pack. Their field definitions and examples are at https://sudokumax.com/developers.
6. Show how I can ask: "Make 20 beginner Sudoku worksheets, include answer sheets, and give me a playable link for each one." Use create_worksheet_pack with {"count":20,"difficulty":"beginner","includeAnswers":true,"paper":"a4"}. Return the actual PDF, collection and individual playable links from the tool response. PDF download links expire after 24 hours.

API calls are free with required attribution. Everything published online must visibly hyperlink to https://sudokumax.com. Offline outputs must print sudokumax.com. Keep the credit on every worksheet and answer sheet. Never fabricate tool results or output URLs.

Manual configuration

1. Create an API key. Sign up and generate a free key. Keep it in your client’s private settings.
2. Add the remote server. In Cursor, add the configuration below to your MCP settings. In Claude, open Customize → Connectors → Add custom connector, enter the server URL, and add Authorization under Request headers with value Bearer YOUR_API_KEY.
3. Verify the connection. Enable the server, refresh the tool list and run the first request below. A saved configuration alone does not confirm a working connection.

{
  "mcpServers": {
    "sudokumax": {
      "url": "https://sudokumax.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY in your client settings. Every request needs the header. The endpoint is stateless and returns JSON; it does not provide an SSE subscription.

Client compatibility

Cursor supports remote MCP configuration. Claude supports custom request headers where custom connectors are available. Direct ChatGPT integration needs OAuth support, which this server does not yet implement.

Client documentation: Cursor · Claude · ChatGPT authentication

Your first request

After connecting, paste this into your assistant:

Generate one beginner Sudoku puzzle using Sudokumax. Show me the puzzle, explain its difficulty analysis, and include the required website credit.

Your assistant should call generate_puzzles with {"count":1,"difficulty":"beginner"}. Expect an 81-cell puzzle, its solution, a difficulty analysis and attribution.

Create a complete worksheet pack

Make 20 beginner Sudoku worksheets on A4 paper, include answer sheets, and give me a playable link for each one. Use Sudokumax and keep its website credit on every published output.

This uses create_worksheet_pack and returns a PDF download, a collection page and individual playable links. With answers included, the PDF has 40 pages. Download links expire after 24 hours; public playable links do not use that expiration.

Available tools

Each tool has the same input fields and operation output as its REST counterpart.

[generate_puzzles

Generate verified puzzles and solutions.

Fields & examples →](https://sudokumax.com/developers/api/generate) [check_uniqueness

Check whether a grid has exactly one solution.

Fields & examples →](https://sudokumax.com/developers/api/check) [analyze_difficulty

Inspect clue counts and supported solving techniques.

Fields & examples →](https://sudokumax.com/developers/api/analyze) [validate_progress

Check player entries and completion.

Fields & examples →](https://sudokumax.com/developers/api/validate) [get_hint

Get one explained singles placement.

Fields & examples →](https://sudokumax.com/developers/api/hint) [publish_puzzles

Create a collection and playable puzzle links.

Fields & examples →](https://sudokumax.com/developers/api/publish) [export_worksheets

Turn your grids into a printable PDF.

Fields & examples →](https://sudokumax.com/developers/api/worksheets) [create_worksheet_pack

Generate puzzles, PDFs, answers and links together.

Fields & examples →](https://sudokumax.com/developers/api/packs)

Responses & errors

The client initializes the connection before calling tools. Here is the protocol request for the worksheet example:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "create_worksheet_pack",
    "arguments": {
      "count": 20,
      "difficulty": "beginner",
      "includeAnswers": true,
      "paper": "a4"
    }
  }
}

A successful response includes the operation result in structuredContent and as JSON in content[0].text. A pack includes pdfUrl, pdfExpiresAt, collectionUrl, puzzles[].playableUrl and attribution.

Example tool error

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "NOT_UNIQUE: Puzzle verification returned multiple; a verified unique solution is required."
      }
    ]
  }
}

Operation errors set isError: true. Missing or revoked keys fail at the HTTP layer with 401 or 403. Invalid MCP input can produce a protocol validation error. For 429 responses, wait for the Retry-After period before retrying.

Limits & error reference →

Local stdio adapter

For clients that launch MCP processes, build the adapter from the website repository. It calls the authenticated REST API, so it still requires network access and an active key.

npm ci
npm run build:engine

{
  "mcpServers": {
    "sudokumax": {
      "command": "node",
      "args": [
        "/absolute/path/to/website/packages/puzzle-engine/dist/stdio.js"
      ],
      "env": {
        "SUDOKUMAX_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Replace the absolute executable path and configure the key in your client. Set SUDOKUMAX_SITE_URL to test against a local website. Non-local API origins must use HTTPS. Standard output is reserved for MCP messages. The npm package is prepared in the repository; publication is pending.

Resources, prompts & attribution

The server exposes the sudokumax://developers resource and a classroom-worksheets prompt for a twenty-puzzle beginner pack.

API calls are free with attribution. Online outputs must visibly link to sudokumax.com; offline outputs must print the website address. Keep the credit already included on every generated worksheet and answer sheet.

Read the attribution terms →