Skip to main content
Glama
scorezilla-mcp
by isco-tec

scorezilla-mcp

npm version license: MIT scorezilla-mcp MCP server

Add a global leaderboard to your game by asking Claude Code or Cursor. The SDK it wires in is ~5 KB gzipped, with zero runtime dependencies.

Official Model Context Protocol (MCP) server for Scorezilla. Connect it to your AI coding assistant (Claude Code, Cursor, Continue.dev, …) and ship a working leaderboard without leaving your editor.

What you can ask the AI to do

  • "Add a leaderboard to my game" → it bootstraps a game + board and pastes ready-to-run TypeScript SDK code into your project

  • "What did my last test score rank?" → it reads your live leaderboard

  • "List my games" / "show me the boards on X" → it inspects what you already have

Eleven tools total — five read-only, and six that write: four that create resources (bootstrap_leaderboard, create_game, create_board, mint_key) plus two that update config (update_board_config — score bounds + retention, e.g. an anti-cheat maxScore; update_game_config — the browser-submit origin allowlist).

Related MCP server: Nhost MCP Server

Install + configure

Access — open to every Scorezilla account. Sign up free at dashboard.scorezilla.dev, create a token, and go. Creating games and boards counts toward your plan's limits (Free: 2 games × 3 boards each); when you hit one, the tool error includes a direct upgrade link. See pricing.

1. Get a token

Sign in at dashboard.scorezilla.dev, open MCP tokens, click Create token. Copy the mcp_live_* value once — it's not shown again.

2. Add the server to your AI coding assistant

Claude Code — one command (--scope user makes it available in every project):

claude mcp add scorezilla --scope user -e SCOREZILLA_TOKEN=mcp_live_… -- npx -y @scorezilla/mcp

Cursor — add this to ~/.cursor/mcp.json (or Settings → MCP → Add new MCP server):

{
  "mcpServers": {
    "scorezilla": {
      "command": "npx",
      "args": ["-y", "@scorezilla/mcp"],
      "env": {
        "SCOREZILLA_TOKEN": "mcp_live_…"
      }
    }
  }
}

🔒 Keep your MCP config private. Both clients store the token in plaintext (~/.claude.json for Claude Code, ~/.cursor/mcp.json for Cursor). Don't commit it to git, sync it to a public dotfiles repo, or back it up to a shared location. On macOS/Linux, chmod 600 the file so only your user can read it. If a token leaks, revoke it at dashboard.scorezilla.dev/account/tokens.

Claude Desktop — one click: download scorezilla-mcp.mcpb from the latest release, double-click it, and paste your mcp_live_… token when Claude Desktop asks. The token is kept in your system's secure credential store.

Anything else MCP-compatible — point your client at npx -y @scorezilla/mcp with SCOREZILLA_TOKEN set in the environment.

3. Ask away

In Claude Code or Cursor: "Add a Scorezilla leaderboard to this game."

Tools

Tool

What it does

list_games

Lists your games. Use this first to orient.

list_boards

Lists leaderboards under a game, with each board's ranking, score kind, retention, bounds and period (all-time or daily).

get_keys

Returns the public key (safe to embed) and the secret-key prefix. The full secret never leaves the dashboard.

get_board_top_n

Returns the top entries on a board. The "is my integration working?" tool.

get_sdk_snippet

Returns ready-to-paste integration code for a board. Optional axis args tailor it: anonymous/OAuth identity, client-only vs. server-validated anti-cheat, and the server language (TS/Python/Go/C#).

bootstrap_leaderboard

Creates a new game + first board in one call, then returns the widget embed + SDK snippet + a plain-English recommendation. Same optional axis args (anti-cheat, OAuth, server language). The 90-second-demo path.

create_game

Creates a new (empty) game. Use when a game already exists (so bootstrap_leaderboard would conflict) or you want another.

create_board

Adds a leaderboard board to an existing game (by gameId), with full options (sortDir, scoreKind, retention, bounds, period). Pass period: "daily_utc" for a Daily Challenge board that starts empty every UTC day (past days stay readable); the default none is one all-time ranking. The period is fixed at creation.

mint_key

Mints a fresh public/secret key pair for an existing game. The secret is shown once.

update_board_config

Changes a board's score bounds (e.g. an anti-cheat maxScore) and retention. Partial updates; null clears a bound. A board's period can't be changed; create a new board instead.

update_game_config

Sets a game's browser-submit origin allowlist (e.g. https://yourgame.com, *.yourgame.com). An empty list allows all origins.

Retries

The create tools (bootstrap_leaderboard, create_game, create_board, mint_key) send an Idempotency-Key derived from their arguments. If a call times out and your assistant retries it with the same arguments within 5 minutes, the API returns the original result instead of creating a duplicate: the same game and board for bootstrap_leaderboard, the same key pair for mint_key.

After that window, or if bootstrap_leaderboard returns partial_failure or slug_taken_active, don't bootstrap again. Call list_games (and list_boards) to see what exists, then finish with create_board or mint_key.

Plan limits

Creating games and boards counts toward your Scorezilla plan's limits (Free: 2 games × 3 boards each; see pricing). When a write would go past a limit, the tool returns a plan_limit error with the limit and a direct upgrade link, which your assistant can pass on. Nothing is ever billed automatically. Requests are also rate-limited per token and per account; a rate_limited error says when to retry.

Flags

scorezilla-mcp [--read-only] [--base-url=<url>] [--version] [--help]
  • --read-only — refuse to register the write tools (bootstrap_leaderboard, create_game, create_board, mint_key, update_board_config, update_game_config). Use this on shared/CI configs to guarantee the AI can't create or change resources.

  • --base-url=<url> — override the API origin. Defaults to https://api.scorezilla.dev. Useful for self-hosted or staging environments.

Env vars

  • SCOREZILLA_TOKEN — required. Bearer token issued at dashboard.scorezilla.dev/account/tokens.

  • SCOREZILLA_BASE_URL — same as --base-url, but via env. CLI flag wins if both are set.

  • SCOREZILLA_BETA_TOKEN — no longer needed; the MCP is open to every account. Kept for compatibility (sent as X-MCP-Beta when set).

Tokens: how they work

  • Tokens are scoped to the developer who issued them and see every game associated with their account.

  • The MCP server never returns the secret-key plaintext for a game — for that, copy from the dashboard.

  • Revoke a token any time at dashboard.scorezilla.dev/account/tokens. Revocations propagate within a few seconds.

  • Tokens are bearer credentials: anyone with the value can call the API on your behalf. Don't commit them to source; don't paste them into shared chats. Keep them in env blocks, password managers, or secret stores.

Runtime requirements

  • Node ≥ 20

  • A network path to https://api.scorezilla.dev

Releasing

Releases are CI-driven and require an approval click in the npm-publish GitHub Environment. The full flow:

  1. Author a changeset locally: pnpm changeset — describes what changed and the bump type. Commit the file under .changeset/.

  2. Merge to main. .github/workflows/release.yml runs and opens a "chore(release): version @scorezilla/mcp" PR that bumps package.json, syncs server.json (the MCP Registry manifest) via scripts/sync-server-json-version.mjs, and updates CHANGELOG.md.

  3. Merge the version PR. The same workflow then publishes:

    • npm tarball with --provenance (verifiable build attestation via GH OIDC + sigstore), plus a @scorezilla/mcp@<version> git tag and GitHub release (notes from CHANGELOG.md)

    • Post-publish smoke test that installs the published tarball and runs the binary

    • MCP Registry record via mcp-publisher login github-oidc → mcp-publisher publish, only after the smoke test passes; it waits for npm to serve the version and retries while the Registry can't see it yet

  4. Pre-flight guards that run before publish: typecheck, test, build, bin smoke (node dist/index.js --version), and release:check (asserts package.json and server.json versions agree).

Manual publishes from a developer terminal still work (bash scripts/publish.sh) but aren't the path CI takes — they skip provenance and approval gates. Use only for one-off recovery.

Issues / feedback

GitHub Issues.

License

MIT.

Available Tools

11 tools
bootstrap_leaderboardA

Use this when starting from scratch — creates a new game AND its first board in one call, then returns ready-to-paste integration code wired against the board. The fastest path from "I want a leaderboard" to "scores are flowing." Do NOT call this if the developer already has games — call list_games first and use bootstrap_leaderboard only when no game exists yet. The response includes snippets.sdk (framework/server code), snippets.widget (a themeable drop-in HTML embed; null for server_only), and a plain-English recommendation to relay to the developer — paste snippets.sdk (and/or snippets.widget) into their code. The optional axis args tailor the output: set hostingPattern='client_with_server' for anti-cheat (server-validated scores), playerIdentityStrategy='auth_provider' (+ authProvider) for OAuth identity, or serverLanguage for a non-TypeScript server. Omit them all for the simplest anonymous + client-only setup. Retry-safe: if a call times out or the connection drops, calling it again with the SAME arguments within 5 minutes returns the original game and board instead of creating a duplicate. After that window, or on a partial_failure or slug_taken_active error, do NOT bootstrap again — call list_games to see what was created, then finish with create_board / mint_key.

Inputs: gameName (required), gameSlug (required), boardName (required), boardSlug (required), +6 more.

create_boardA

Add a leaderboard board to an EXISTING game (by gameId — get it from list_games). This is how you add boards to a game that already exists; bootstrap_leaderboard only works for brand-new games. sortDir "desc" = high-scores-win, "asc" = lowest-time-wins. Returns the created board including its id.

Inputs: name (required), slug (required), gameId (required), sortDir, +5 more.

create_gameA

Create a new (empty) game in the developer's account. Use this when they ALREADY have a game (so bootstrap_leaderboard would conflict) or want an additional game — call list_games first to check. Returns the gameId; follow up with create_board to add leaderboards and mint_key for keys. For a first-ever game from scratch, prefer bootstrap_leaderboard (it does game + board + keys + code in one call).

Inputs: name (required), slug (required).

get_board_top_nA

Get the top-ranked entries on a leaderboard. Call this after the developer submits a test score to confirm the integration is wired correctly — they will see their own test entry appear. Also useful for displaying current standings.

Inputs: boardId (required), n.

get_keysA

Get a game's API keys. Returns, per key: kind ('public' | 'secret'), prefix, createdAt, and rotation/revocation timestamps. The PUBLIC key includes its full plaintext (it's safe to embed in client code). The SECRET key's plaintext is ALWAYS null over MCP — only its prefix is shown, for identification. Use this to retrieve the public key for a client_only integration, or to check which keys exist / have been revoked. If the developer needs the full SECRET key (for a client_with_server / server_only anti-cheat setup), direct them to https://dashboard.scorezilla.dev — the Keys section under their game — since it never leaves the dashboard.

Inputs: gameId (required).

get_sdk_snippetA

Call this whenever the developer asks how to submit a score, initialize the SDK, or integrate a leaderboard into their code — INCLUDING when they want a setup other than the default: anti-cheat (server-validated scores), OAuth player identity, or a non-TypeScript server. Returns a ready-to-paste integration snippet (the snippet field) tailored to the axis arguments. Omit the axis args for the simplest anonymous + client-only TypeScript setup; set hostingPattern='client_with_server' (+ a serverLanguage and/or auth provider) for the secure anti-cheat path. Use it right after bootstrap_leaderboard, or any time the developer needs the integration code again or wants to switch approach. (For the drop-in widget HTML embed, bootstrap_leaderboard returns it as snippets.widget.)

Inputs: gameId (required), boardId (required), authProvider, hostingPattern, +2 more.

list_boardsA

List all leaderboards (boards) under a given game. Each board has its own id, slug, ranking (sortDir: desc = high-score-wins, asc = lowest-time-wins), score kind (integer / duration_ms / float), retention policy, and optional min/max score bounds. Call this to find a board's id before generating a snippet (get_sdk_snippet) or reading standings (get_board_top_n), or to show the developer what boards already exist under a game returned by list_games.

Inputs: gameId (required).

list_gamesA

List all games owned by the authenticated developer. Returns each game with id, slug, name, and createdAt. Use this first to orient before creating new resources or inspecting an existing game. If the result is an empty list and the developer wants to add a leaderboard, call bootstrap_leaderboard next.

Inputs: no named parameters.

mint_keyA

Mint a fresh public/secret key pair for an EXISTING game (by gameId). Returns publicKey (pk_ — safe for the browser/widget) and secretKey (sk_ — server-only, shown ONCE; tell the developer to store it now). Use when a game needs keys, or to add another pair. Key revocation/rotation is done in the dashboard. Note: the secret also appears in this MCP host's tool-call transcript, so treat the conversation as sensitive until cleared.

Inputs: gameId (required).

update_board_configA

Update a board's scoring config AFTER creation (by gameId + boardId — from list_games / list_boards). PARTIAL: only the fields you pass change. Use it to cap scores for anti-cheat (maxScore), set a floor (minScore), or change retention. A bound can be cleared by passing null. Returns the full updated board.

Inputs: gameId (required), boardId (required), maxScore, minScore, +2 more.

update_game_configA

Set a game's allowed-origins allowlist AFTER creation (by gameId — from list_games). Restricts browser score submissions to specific web origins: an exact origin like "https://yourgame.com" or a wildcard host like "*.yourgame.com" (up to 20). Pass an empty array to allow all origins (the default). Returns the normalized stored list. Gates browser requests only — server-to-server calls send no Origin header.

Inputs: gameId (required), allowedOrigins (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 11 tools

    Disambiguation4/5

    Most tools target a distinct resource/action, and the descriptions explicitly route agents between bootstrap_leaderboard and the lower-level create_game/create_board/mint_key/get_sdk_snippet flow. The main overlap is that bootstrap_leaderboard composes several other tools, but the guidance reduces practical confusion.

    Naming Consistency5/5

    All tool names follow a clear snake_case verb_noun pattern: list_games, create_board, get_keys, update_board_config, etc. Verb choices vary appropriately by operation while the overall convention remains predictable.

    Tool Count5/5

    At 11 tools, the set is well-scoped for game/leaderboard setup, key management, snippets, standings, and config updates. The composite bootstrap tool helps keep the count lean rather than adding redundant create-everything tools.

    Completeness4/5

    Core workflows are covered: create/list games and boards, mint/read keys, generate SDK snippets, inspect top scores, and update configuration. Gaps are minor and mostly administrative—no MCP delete/rename for games or boards, and key rotation/revocation is delegated to the dashboard.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers