Sudokumax

Gere quebra-cabeças de Sudoku verificados, pacotes de planilhas imprimíveis com folhas de respostas e coleções jogáveis por meio de assistentes de IA.

Ver em sudokumax.comExperimente este MCPPatrocinado

Servidor MCP hospedado

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

Instala no Claude Code, Codex, Cursor e outros

Documentação

On this page

Download the Printable Sudoku Worksheet Creator skill →

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. Use a client that supports Streamable HTTP and custom Authorization headers. Add the configuration below where your client accepts remote MCP servers. If your client only launches local processes, use the downloadable stdio adapter below.
  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

The remote endpoint and local adapter are tested with the official MCP client SDK. Individual assistant interfaces and plan restrictions vary; this is not a claim that every Claude, Cursor or ChatGPT installation has been tested. If a connector requires OAuth or cannot send a custom header, use a supported local stdio client instead. This server does not currently implement OAuth.

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 and the default layout, the PDF has 40 pages. Download links expire after 24 hours; public playable links do not use that expiration.

Available tools

Each tool declares input and output schemas and returns the same operation output as its REST counterpart. Publishing and exports are marked as writes; generation and exports are not marked idempotent.

[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 an explained placement, optionally with candidate deductions.

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)

Four additional tools manage private libraries: library_list, library_get, library_save and library_delete. They need library scopes; they do not publish entries. Full private library reference →

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": "MULTIPLE_SOLUTIONS: This puzzle has more than one solution. A puzzle with exactly one 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 →

Install the local stdio adapter

Download developer kit 1.2.0. No private repository access or unpublished npm package is needed. Install Node.js 22.13+ and npm first. The adapter calls the hosted API and requires network access and an active API key.

unzip sudokumax-developer-kit-1.2.0.zip
cd sudokumax-developer-kit-1.2.0
npm ci
cp .env.example .env
# Edit .env locally and set SUDOKUMAX_API_KEY.
npm run smoke

The smoke test lists all twelve tools, checks their output schemas and generates one beginner puzzle. A successful test confirms your key and the adapter can reach the service.

{
  "mcpServers": {
    "sudokumax": {
      "command": "node",
      "args": [
        "/absolute/path/to/sudokumax-developer-kit-1.2.0/mcp.mjs"
      ],
      "env": {
        "SUDOKUMAX_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Replace the absolute path and key. Windows JSON paths need escaped backslashes or forward slashes. If your assistant cannot find node, use the full Node executable path. The client configuration supplies the key; do not assume the assistant loads the kit’s .env.

Set SUDOKUMAX_SITE_URL only to target a different trusted environment. Non-local origins must use HTTPS. Standard output is reserved for MCP messages. Full starter app and clients · Checksum and version.

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 →