Skip to main content
Glama
SAIR MCP Server
by osick

sair-mcp

A local MCP (Model Context Protocol) server that exposes the SAIR Competition Public API as tools for an MCP client (Claude Code, Claude Desktop, or any other MCP-compatible client).

It covers the full documented API surface: account introspection, competitions (browsing, eligibility, leaderboards, submissions, IGP24 label progress), Playground (models, problem sets, runs, results, live event streaming, usage), your private cheatsheet and Lean solver-template libraries, custom Lean problems, and the Contributor Network (browsing, publishing, favoriting, commenting, lineage graphs, benchmarks).

Installation

Requires Python 3.10+.

git clone <this-repo>
cd SAIRmcp
pip install -e .

Related MCP server: codabench-mcp

Getting a SAIR API key

  1. Sign in to SAIR and open Account settings -> API keys.

  2. Create a key and select the scopes you need. At minimum, for the examples below: competition.read and competition.write. Add playground.read / playground.write for Playground tools, contributor-network.read / contributor-network.write for Contributor Network tools.

  3. Copy the key immediately -- it is shown only once. Keys look like sair_a1b2c3d4_zR9....

Configuration

Set these environment variables before starting the server:

Variable

Required

Default

Purpose

SAIR_API_KEY

Yes

-

Your personal SAIR API key. The server refuses to start without it.

SAIR_BASE_URL

No

https://api.sair.foundation/api/public/v1

Override for testing against a different environment.

Running it standalone

python -m sair_mcp

This starts the server on stdio and blocks, waiting for an MCP client to connect. There is no output on success; it's meant to be launched by an MCP client, not run interactively.

Registering with Claude Code and other mcp clients

Add to your project's .mcp.json (or user-level MCP config)

{
  "mcpServers": {
    "sair": {
      "command": "python",
      "args": ["-m", "sair_mcp"],
      "env": {
        "SAIR_API_KEY": "sair_a1b2c3d4_zR9..."
      }
    }
  }
}

Or via the CLI, substituting the same absolute path:

claude mcp add sair -- python3 -m sair_mcp

(then set SAIR_API_KEY in your shell environment before launching Claude Code, or add it to the env block above).

Alternative: pyproject.toml also declares a sair-mcp console-script entry point, so once installed you can skip -m sair_mcp entirely and point command straight at that script's absolute path instead -- again, resolve it in the same command as the install so it can't drift to a different environment's sair-mcp:

pip install -e . && which sair-mcp

No args needed when using this form.

If you use a dedicated virtual environment for this project (recommended for isolation from other Python projects), the same rule applies: use <path-to-venv>/bin/python (or <path-to-venv>/bin/sair-mcp) as command, not a bare python.

Registering with Claude Desktop

Add the same shape to claude_desktop_config.json under mcpServers, using the same absolute-interpreter-path command as above -- Desktop's subprocess environment is even less likely than a terminal's to have your Python environment on PATH.

Usage example

A typical end-to-end flow, as an MCP client would call it:

  1. get_me -- confirm the key is valid and see its scopes.

  2. list_competitions -- find a competition ID.

  3. get_competition("modular-arithmetic-challenge") -- read submissionSpec to learn the required payload shape.

  4. get_my_participation("modular-arithmetic-challenge") -- check canSubmit before attempting anything.

  5. submit_competition_entry("modular-arithmetic-challenge", payload={"modelName": "you/your-model", "commitHash": "0123...(40 hex chars)"}).

  6. get_my_submission("modular-arithmetic-challenge") -- confirm the active submission.

Tool reference

All tools return the API's unwrapped data object as a dict (or None for 204 responses, or a plain string for the two text-returning tools). On error, the tool call fails with a SairApiError-derived message in the form [<http status> <error code>] <message>; consult SAIR's Errors documentation for the full code table.

Account (1 tool)

Tool

Scope

Purpose

get_me

none

Confirm the API key and see its owner + granted scopes.

Competitions (10 tools)

Tool

Scope

Purpose

list_competitions

competition.read

List competitions visible through the API.

get_competition

competition.read

Get one competition's detail and submissionSpec.

get_my_participation

competition.read

Check canSubmit / submitBlockedReason for one competition.

get_leaderboard

competition.read

List published leaderboard rows.

get_my_leaderboard_standing

competition.read

Get the caller's own leaderboard entry.

submit_competition_entry

competition.write

Create or replace the caller's submission.

get_my_submission

competition.read

Read the caller's current submission (or history, for IGP24).

get_submission_by_id

competition.read

Read one submission by ID.

download_submission_text

competition.read

Download the stored text body of a submission.

get_igp24_label_progress

competition.read

Bulk aggregate IGP24 discovery progress by label.

Playground (10 tools)

Tool

Scope

Purpose

list_playground_models

playground.read

List model IDs accepted in runs for a competition.

list_playground_problem_sets

playground.read

List available practice problem sets.

get_playground_problem_set

playground.read

Get every problem in one problem set.

submit_playground_run

playground.write

Create a practice run.

list_playground_runs

playground.read

List the caller's runs for a competition.

get_playground_run

playground.read

Get one run's params, summary, and timing.

cancel_playground_run

playground.write

Cancel a pending/running run.

list_playground_run_results

playground.read

List per-cell/per-problem result rows for a run.

stream_playground_run_events

playground.read

Collect live verdict events for a solver-participation run (blocks up to a timeout).

get_playground_usage

playground.read

Get the caller's practice credit/usage counters.

Cheatsheets (5 tools)

Tool

Scope

Purpose

list_cheatsheets

playground.read

List the caller's cheatsheets.

get_cheatsheet

playground.read

Get one cheatsheet including its content.

create_cheatsheet

playground.write

Create a cheatsheet.

update_cheatsheet

playground.write

Update a cheatsheet's title/content.

delete_cheatsheet

playground.write

Delete a cheatsheet.

Solver templates (5 tools)

Tool

Scope

Purpose

list_solver_templates

playground.read

List the caller's Lean solver templates.

get_solver_template

playground.read

Get one solver template including its source.

create_solver_template

playground.write

Create a solver template.

update_solver_template

playground.write

Update a solver template's title/source.

delete_solver_template

playground.write

Delete a solver template.

Custom Lean problems (4 tools)

Tool

Scope

Purpose

list_custom_problems

playground.read

List the caller's private Lean statement pairs.

get_custom_problem

playground.read

Get one custom problem.

create_custom_problem

playground.write

Create an immutable custom Lean problem.

delete_custom_problem

playground.write

Delete a custom problem.

Contributor Network (13 tools)

Tool

Scope

Purpose

list_contributor_network_items

contributor-network.read

Browse shared cheatsheets/solver templates/model references.

get_contributor_network_item

contributor-network.read

Get one item's full payload.

publish_contributor_network_item

contributor-network.write

Publish a saved resource, submission body, inline text, or model reference.

withdraw_contributor_network_item

contributor-network.write

Withdraw (unpublish) an item you authored.

favorite_contributor_network_item

contributor-network.write

Favorite an item.

unfavorite_contributor_network_item

contributor-network.write

Unfavorite an item.

list_contributor_network_comments

contributor-network.read

List comments on an item.

create_contributor_network_comment

contributor-network.write

Post a comment.

delete_contributor_network_comment

contributor-network.write

Delete a comment.

get_contributor_network_item_graph

contributor-network.read

Get the lineage subgraph rooted at one item.

get_contributor_network_global_graph

contributor-network.read

Get the lineage graph across all visible items.

list_contributor_network_benchmarks

contributor-network.read

List platform-run benchmark summaries.

get_contributor_network_item_benchmark

contributor-network.read

Get the per-model benchmark breakdown for one item.

Total: 48 tools.

Development

pip install -e ".[dev]"
pytest --cov=sair_mcp --cov-report=term-missing

All tests run against a mocked HTTP layer (respx) -- no test requires or uses a real SAIR_API_KEY or makes a real network call.

License

MIT -- see LICENSE.

Available Tools

48 tools
cancel_playground_runA

Cancel a pending or running Playground run.

Scope: playground.write. Already-terminal runs raise RUN_NOT_CANCELLABLE (409).

Inputs: run_id (required), competition_id (required).

create_cheatsheetA

Create a cheatsheet owned by the calling account.

Scope: playground.write. Can be referenced from a Playground run (configurations[].cheatsheet) and submitted to a cheatsheet-kind competition.

Inputs: title (required), content (required), source_contributor_network_item_id.

create_contributor_network_commentA

Create a comment on an item.

Scope: contributor-network.write. body must be non-empty after trim and at most 5000 characters.

Inputs: body (required), item_id (required).

create_custom_problemA

Create an immutable private Lean statement pair.

Scope: playground.write. lhs_name/rhs_name are derived automatically if omitted. Use the returned id in problemIds for a solver-participation Playground run.

Inputs: lhs_text (required), rhs_text (required), lhs_name, rhs_name.

create_solver_templateA

Create a solver template owned by the calling account.

Scope: playground.write. track defaults to "solo" server-side if omitted. Can be copied into a Playground run and submitted to a solver-participation competition.

Inputs: title (required), solver_code (required), track, source_contributor_network_item_id.

delete_cheatsheetA

Delete a cheatsheet owned by the calling account.

Scope: playground.write. Raises CHEATSHEET_LOCKED (403) if published on the Contributor Network -- withdraw it first.

Inputs: cheatsheet_id (required). Returns: result

delete_contributor_network_commentA

Soft-delete a comment.

Scope: contributor-network.write. Callers may delete their own comments; item authors may delete any comment on their own items.

Inputs: item_id (required), comment_id (required). Returns: result

delete_custom_problemA

Delete a custom Lean problem owned by the calling account.

Scope: playground.write. Existing runs that referenced the problem keep their own stored copy and history.

Inputs: problem_id (required). Returns: result

delete_solver_templateA

Delete a solver template owned by the calling account.

Scope: playground.write. Raises SOLVER_TEMPLATE_LOCKED (403) if published on the Contributor Network -- withdraw it first.

Inputs: template_id (required). Returns: result

download_submission_textA

Download the stored text body of a submission as plain text.

Scope: competition.read. Returns payload.content (cheatsheet), payload.solverCode (solver-participation), or newline-joined payload.polynomials (igp24-polynomial). Raises NO_DOWNLOAD_FOR_KIND for model-reference submissions, which have no text body.

Inputs: submission_id (required), competition_id (required). Returns: result

favorite_contributor_network_itemA

Set the caller's favorite flag for an item (idempotent).

Scope: contributor-network.write.

Inputs: item_id (required).

get_cheatsheetB

Get one cheatsheet, including its content body.

Scope: playground.read.

Inputs: cheatsheet_id (required).

get_competitionA

Get one competition's detail, including its submissionSpec.

Scope: competition.read. submissionSpec (schema, metaSchema, permission, window, limits, catalog) is the only source of truth for how to build a submission payload for this competition -- read it before calling submit_competition_entry or submit_playground_run.

Inputs: competition_id (required).

get_contributor_network_global_graphA

Get the lineage graph across all visible items.

Scope: contributor-network.read. Capped at 2000 nodes -- add competition_id/kind filters if you hit GRAPH_TOO_LARGE (413).

Inputs: kind, competition_id.

get_contributor_network_itemA

Get one Contributor Network item with its full payload.

Scope: contributor-network.read. Includes content (cheatsheet), solverCode (solver-template), or modelName/commitHash (model-reference), plus parent lineage.

Inputs: item_id (required).

get_contributor_network_item_benchmarkC

Get the per-model benchmark breakdown for one item.

Scope: contributor-network.read.

Inputs: item_id (required).

get_contributor_network_item_graphA

Get the lineage subgraph rooted at one item (ancestors + descendants).

Scope: contributor-network.read. depth in the response is relative to the anchor item: negative for ancestors, 0 for the anchor itself.

Inputs: item_id (required).

get_custom_problemA

Get one custom Lean problem owned by the calling account.

Scope: playground.read.

Inputs: problem_id (required).

get_igp24_label_progressA

Get aggregate IGP24 participant progress by transitive group label.

Scope: competition.read. Bulk aggregate endpoint over the ~25,000-label IGP24 universe; returns data.labels[] rather than data.items[]. Before publication returns labels: [], meta.published: false. limit defaults to 100 and maxes at 5000 (higher than the default list-endpoint max) so a full sweep takes about 5 requests. label is a repeatable filter list (e.g. ["24T1", "24T3"]); labels is the same filter as one comma-separated string -- use one or the other. Changing filters invalidates a previous cursor.

Inputs: label, limit, cursor, labels, +1 more.

get_leaderboardA

List published leaderboard rows for a competition.

Scope: competition.read. Cursor-paginated. Always returns 200; use data.meta.published (not the emptiness of items) to tell whether the leaderboard has been published yet.

Inputs: competition_id (required), limit, cursor.

get_meA

Return the API key in use and its owner.

Scope: none -- works with any valid key. Call this first to verify a key is valid and to inspect its granted scopes before calling scope-gated endpoints.

Inputs: no named parameters.

get_my_leaderboard_standingA

Get the caller's own leaderboard entry for a competition.

Scope: competition.read. Returns {"entry": null} when the caller isn't ranked yet (no team, no scoring placements, or leaderboard unpublished).

Inputs: competition_id (required).

get_my_participationA

Get the caller's participation status in one competition.

Scope: competition.read. Returns canSubmit and, when false, submitBlockedReason (EMAIL_NOT_VERIFIED, NOT_ENROLLED, NOT_TEAM_OWNER, BEFORE_WINDOW, AFTER_WINDOW). Treat this as the source of truth for whether a submission should be attempted right now.

Inputs: competition_id (required).

get_my_submissionA

Get the caller's current submission for a competition.

Scope: competition.read. For cheatsheet / model-reference / solver-participation this returns a single submission record (404 if none exists yet); pass track for track-based competitions. For igp24-polynomial this instead returns a cursor-paginated list of every past submission (newest first) -- cursor/limit apply only to that kind and are ignored for the others.

Inputs: competition_id (required), limit, track, cursor.

get_playground_problem_setB

Get every problem in one Playground problem set (not paginated).

Scope: playground.read. Row shape depends on competition kind: equation problems (index, equation1, equation2, goldAnswer) for cheatsheet competitions, Lean problems (id, lhsName, lhsText, rhsName, rhsText, isCustom) for solver-participation competitions.

Inputs: competition_id (required), problem_set_id (required).

get_playground_runB

Get one Playground run: params, summary, and timing.

Scope: playground.read. Lean competitions also include verdicts[].

Inputs: run_id (required), competition_id (required).

get_playground_usageA

Get the caller's accumulated Playground practice spend for this competition.

Scope: playground.read. Returns credit balance, run counters, and either cellsExecuted (equation-style) or problemsAttempted (Lean / model-reference).

Inputs: competition_id (required).

get_solver_templateB

Get one solver template, including its Lean 4 solverCode.

Scope: playground.read.

Inputs: template_id (required).

get_submission_by_idA

Get one submission by ID.

Scope: competition.read. The caller can only read submissions they are allowed to access for this competition.

Inputs: submission_id (required), competition_id (required).

list_cheatsheetsB

List cheatsheets owned by the calling account (content omitted).

Scope: playground.read.

Inputs: limit, cursor.

list_competitionsA

List competitions visible through the public API.

Scope: competition.read. Cursor-paginated (default limit 25, max 100): pass the previous response's nextCursor to fetch the next page; a nextCursor of null means there are no more pages.

Inputs: limit, cursor.

list_contributor_network_benchmarksA

List platform-run benchmark summaries for published items.

Scope: contributor-network.read. Benchmarks are platform-scheduled, not user-triggered. sort_by is "avgAccuracy" (default), "publishedAt", or "scoredTotal"; sort_direction is "desc" (default) or "asc".

Inputs: limit, cursor, search, sort_by, +5 more.

list_contributor_network_commentsA

List comments on an item, oldest first.

Scope: contributor-network.read. Soft-deleted comments remain for thread continuity with body/author.displayName set to null.

Inputs: item_id (required), limit, cursor.

list_contributor_network_itemsA

List visible Contributor Network items (content/solverCode/model fields omitted).

Scope: contributor-network.read. kind is one of cheatsheet / solver-template / model-reference. track applies when kind=solver-template. public_code does an exact lookup by shareable code (e.g. "MAC01-000042") and ignores cursor when given. sort is "newest" (default) or "earliest".

Inputs: kind, sort, limit, track, +4 more.

list_custom_problemsC

List private Lean statement pairs (custom problems) owned by the calling account.

Scope: playground.read.

Inputs: limit, cursor.

list_playground_modelsA

List Playground model IDs accepted in a run for this competition.

Scope: playground.read. Only call this when the competition's capabilities.playground is true. Model IDs are opaque tokens (some are OpenRouter-style provider/name, others are hyphenated) -- don't parse them, just pass the id field back in run requests.

Inputs: competition_id (required), limit, cursor.

list_playground_problem_setsC

List Playground problem sets available for practice runs.

Scope: playground.read.

Inputs: competition_id (required), limit, cursor.

list_playground_run_resultsA

List per-cell/per-problem result rows for a Playground run.

Scope: playground.read. Row shape depends on competition kind (equation / Lean / model-reference result fields).

Inputs: run_id (required), competition_id (required), limit, cursor.

list_playground_runsB

List Playground runs created by the caller for this competition.

Scope: playground.read. status is one of pending/running/done/failed/ cancelled. problem_set applies to equation-style competitions only.

Inputs: competition_id (required), limit, cursor, status, +2 more.

list_solver_templatesA

List solver templates owned by the calling account (solverCode omitted).

Scope: playground.read. track filters by track ID, e.g. "solo" or "marathon".

Inputs: limit, track, cursor.

publish_contributor_network_itemA

Publish a saved resource, a submitted text body, inline text, or a model reference.

Scope: contributor-network.write. kind must match source["from"]: "cheatsheet" (needs source.cheatsheetId), "solver-template" (needs source.solverTemplateId), "submission" (needs source.submissionId -- only for cheatsheet/solver-participation submissions), "inline" (needs source.title plus source.content or source.solverCode), or "model-reference" (needs source.modelName and source.commitHash). track/model_id are required when kind=solver-template and must be omitted when kind=model-reference.

Inputs: kind (required), source (required), competition_id (required), track, +3 more.

stream_playground_run_eventsA

Collect Server-Sent Events for a solver-participation Playground run.

Scope: playground.read. Only available for solver-participation competitions. This blocks for up to timeout_seconds (capped at 300) collecting one LeanVerdict per event as the run progresses, and returns once the run reaches a terminal status (stream closes) or the timeout elapses -- an MCP tool call is a single request/response, so this collects-then-returns rather than truly streaming incrementally. Returns {"verdicts": [...], "ended_reason": "completed" | "timeout"}.

Inputs: run_id (required), competition_id (required), timeout_seconds.

submit_competition_entryA

Create or replace the caller's submission for a competition.

Scope: competition.write. payload's shape is selected by the competition's submissionSpec.kind -- call get_competition first and build payload from submissionSpec.schema. Known kinds today:

  • cheatsheet: {"content": ""}

  • model-reference: {"modelName": "/", "commitHash": "<40-hex-char sha>"}

  • solver-participation: {"track": "", "modelId": "", "solverCode": "<lean 4 source>"}

  • igp24-polynomial: {"polynomials": ["<25 comma-separated coefficients a_0..a_24>", ...]}

meta is optional (e.g. {"description": "...", "contributorNetworkItemId": "..."}), validated against submissionSpec.metaSchema. For igp24-polynomial every call creates a brand-new submission; other kinds overwrite the existing entry for that competition (or track) in place and keep the same submissionId.

Inputs: payload (required), competition_id (required), meta.

submit_playground_runA

Create a Playground practice run.

Scope: playground.write. run_request's shape depends on the competition's submissionSpec.kind -- read get_competition first. Known shapes today:

  • cheatsheet: {"models": ["", ...], "problems": [{"problemSet": "", "index": 0} | {"custom": {"equation1": "...", "equation2": "...", "goldAnswer": true}}, ...], "configurations": [{"cheatsheet": ""}, ...] (optional, omit for an unconditioned baseline), "repeat": 1 (optional, max 5)}

  • solver-participation: {"solverCode": "<lean 4 source>", "solverName": "" (optional), "problemIds": ["", ...], "allowedModels": ["", ...] (optional)}

  • model-reference: {"modelName": "/", "commitHash": "<40-hex-char sha>", "problemSetId": "", "hfToken": "" (optional, for private/gated repos), "note": "<=500 chars" (optional)}

Returns {"runId": ..., "status": "pending"}. Poll get_playground_run / list_playground_run_results for progress.

Inputs: run_request (required), competition_id (required).

unfavorite_contributor_network_itemA

Clear the caller's favorite flag for an item (idempotent).

Scope: contributor-network.write. Refetch the item to read the updated favoriteCount.

Inputs: item_id (required). Returns: result

update_cheatsheetA

Partially update a cheatsheet. Provide at least one field.

Scope: playground.write. Raises CHEATSHEET_LOCKED (403) if the cheatsheet is currently published on the Contributor Network -- withdraw it first.

Inputs: cheatsheet_id (required), title, content.

update_solver_templateA

Partially update a solver template. Provide at least one field.

Scope: playground.write. track and its source item are fixed after creation. Raises SOLVER_TEMPLATE_LOCKED (403) if published on the Contributor Network -- withdraw it first.

Inputs: template_id (required), title, solver_code.

withdraw_contributor_network_itemA

Withdraw (unpublish) an item authored by the calling account.

Scope: contributor-network.write. Withdrawn items disappear from listings, direct lookups, graphs, and benchmark results.

Inputs: item_id (required). Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 48 tools

    Disambiguation4/5

    The tools are mostly distinct, each targeting specific resources and actions. However, the high number of tools (48) introduces some complexity, and a few like 'get_my_submission' vs 'get_submission_by_id' could cause minor confusion despite different purposes.

    Naming Consistency5/5

    Tool names consistently follow the `verb_noun` snake_case pattern (e.g., create_cheatsheet, list_playground_runs). The verbs are appropriately descriptive (create, get, list, delete, update, submit, etc.), and there is no mixing of conventions.

    Tool Count2/5

    With 48 tools, the set is significantly larger than the recommended 3-15 range, indicating over-scoping. While the domain is broad, many operations could be consolidated, and the sheer volume risks overwhelming agents.

    Completeness4/5

    The tool surface covers CRUD operations for core resources (cheatsheets, solver templates, custom problems, contributor network items) and key workflows (competition submissions, playground runs). Minor gaps exist, such as the lack of a tool to list all runs across competitions, but the set is largely complete for its intended domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      A lightweight, local-first MCP server for executing HTTP requests and managing API collections and environments without cloud dependencies. It enables testing APIs, handling authentication, and importing OpenAPI specifications directly within MCP-compatible workflows.
      42
      127 npm
      13
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      MCP server for Codabench REST API that enables AI agents to drive a full participant ML-benchmark workflow: discover competitions, download data, submit, poll, and read leaderboards.
      16
      28 PyPI
      MIT