Model Context Protocol (MCP) integration

Leaderboarded supports the Model Context Protocol (MCP), which lets AI assistants like Claude Desktop read and update your leaderboards through natural conversation — no manual API calls required.

What you can do

Once connected, your AI assistant can:

• Retrieve the current standings on any board
• Update scores for one or more players
• Add a new player with an initial score
• Remove a player from a board

Getting access

The MCP integration is in early access. Email [email protected] and we'll set you up with:

• Your board's API token
• A sample MCP server config
• Support for any integration questions

How it works

Authentication

All API requests are authenticated using a board token. There are two token types:

• Edit token — full access (update scores, add/remove players, read data)
• Scorekeeping token — score updates only (cannot add or remove players)

Find your tokens on the board settings page under API / Integrations.

MCP server configuration

To use Leaderboarded with Claude Desktop, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "leaderboarded": {
      "command": "npx",
      "args": ["-y", "@leaderboarded/mcp-server"],
      "env": {
        "LEADERBOARD_TOKEN": "your-edit-token-here"
      }
    }
  }
}

Once configured, restart Claude Desktop and your board will be available in conversation.

API reference

The MCP integration exposes a REST API. All endpoints use the base URL https://leaderboarded.com/api/mcp/.

GET /board/{token}

Returns the current state of a board.

Example response:

{
  "success": true,
  "board": {
    "id": 12345,
    "title": "Sales Competition Q1",
    "type": "LEADERBOARD"
  },
  "players": [
    { "id": 1, "name": "Sarah", "score": 42 },
    { "id": 2, "name": "John",  "score": 38 }
  ]
}

POST /update-scores/{token}

Updates scores for one or more players. Use an edit token or scorekeeping token.

Request body — add a round (all players at once):

{
  "scores": [
    { "player_id": 1, "score": 5 },
    { "player_id": 2, "score": 3 }
  ],
  "comment": "Week 3 results"
}

Request body — update individual scores:

{
  "scores": [
    { "player_id": 1, "score": 5, "operation": "increment" },
    { "player_id": 2, "score": 10, "operation": "set" }
  ]
}

Supported operation values: increment, decrement, set.

POST /player/{token}

Adds a new player to the board. Requires an edit token.

Request body:

{
  "name": "Alex",
  "score": 15
}

DELETE /player/{token}/{player_id}

Removes a player from the board. Requires an edit token.

Example conversation

Here's what interacting with your leaderboard looks like in Claude Desktop after setup:

You: What are the current standings on the sales leaderboard?

Claude: Here are the current standings: 1. Maya — 45 sales 2. Sarah — 42 sales 3. John — 38 sales 4. Thomas — 29 sales

You: Sarah just closed 3 more deals and John got 2. Update the scores.

Claude: Done — I've added 3 points for Sarah (now 45) and 2 for John (now 40). Maya is no longer in first place; it's now a tie between her and Sarah.

You: Add a new team member: Alex, starting with 15 sales.

Claude: Alex has been added to the leaderboard with a score of 15.

Questions?

Email [email protected] — we're happy to help with setup.