Sudoku MCP server

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 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.

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.

{
  "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.

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.