scorezilla-mcp
This MCP server lets you manage Scorezilla leaderboards from an AI coding assistant.
List your games and the leaderboards under each game.
Read top leaderboard entries to verify integrations or display standings.
Retrieve public API keys and secret-key prefixes for a game.
Generate ready-to-paste SDK snippets tailored by hosting pattern, identity strategy, auth provider, and server language.
Bootstrap a new game plus first leaderboard in one call and return SDK/widget embed code.
Create additional games and boards, including sorting, score type, retention, bounds, and daily period options.
Mint fresh public/secret key pairs for an existing game.
Update board scoring config such as min/max score bounds and retention.
Update a game's browser-submit origin allowlist.
Allows using GitHub as an OAuth provider for player identity in leaderboards, enabling score submissions with GitHub authentication.
scorezilla-mcp
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/mcpCursor — 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.jsonfor Claude Code,~/.cursor/mcp.jsonfor 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 600the 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 |
| Lists your games. Use this first to orient. |
| Lists leaderboards under a game, with each board's ranking, score kind, retention, bounds and |
| Returns the public key (safe to embed) and the secret-key prefix. The full secret never leaves the dashboard. |
| Returns the top entries on a board. The "is my integration working?" tool. |
| 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#). |
| 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. |
| Creates a new (empty) game. Use when a game already exists (so |
| Adds a leaderboard board to an existing game (by |
| Mints a fresh public/secret key pair for an existing game. The secret is shown once. |
| Changes a board's score bounds (e.g. an anti-cheat |
| Sets a game's browser-submit origin allowlist (e.g. |
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 tohttps://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 asX-MCP-Betawhen 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
envblocks, 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:
Author a changeset locally:
pnpm changeset— describes what changed and the bump type. Commit the file under.changeset/.Merge to main.
.github/workflows/release.ymlruns and opens a "chore(release): version @scorezilla/mcp" PR that bumpspackage.json, syncsserver.json(the MCP Registry manifest) viascripts/sync-server-json-version.mjs, and updatesCHANGELOG.md.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 fromCHANGELOG.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
Pre-flight guards that run before publish: typecheck, test, build, bin smoke (
node dist/index.js --version), andrelease:check(assertspackage.jsonandserver.jsonversions 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
License
MIT.
Available Tools
11 toolsbootstrap_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
Scored across 11 tools
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.
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.
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.
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
Related MCP Connectors
Official MCP server for Lovable, the AI-powered full-stack app builder.
Official MCP server for subfeed.app — the cloud for agents. 15+ tools for AI agents to register, build, and deploy other agents. Zero human required. Start here: subfeed.app/skill.md
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
Official MCP server for Softhills 3D/2D Visualization SDKs, API documentation, and code examples.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceOfficial MCP server for exerciseapi.dev — give your AI coding agent direct access to 2,198+ vetted exercises across 12 categories.38 npm3MIT

Nhost MCP Serverofficial
AlicenseNot gradedqualityFmaintenanceOfficial MCP server for the Nhost backend platform. Manage Postgres data, GraphQL, auth, storage, migrations and Hasura metadata via AI assistants.5MIT- AlicenseNot gradedqualityDmaintenanceOfficial MCP server for the Lacuna Music API. Generate AI music — full songs with vocals and lyrics, or instrumentals — with style prompts, task status polling, and audio downloads.5MIT

BlazingCDN-MCPofficial
AlicenseAqualityBmaintenanceOfficial MCP server for BlazingCDN - AI agents (Claude, Cursor, Windsurf) manage CDN resources, purge cache, query metrics, domains, Cloud Storage and Video CDN2973 npm2MIT