SAIR MCP Server
The SAIR MCP Server exposes the SAIR Competition Public API as 48 tools for MCP clients, enabling end-to-end interaction with competitions, practice playground, personal libraries, and community sharing.
Account
Verify your API key and inspect granted scopes (
get_me)
Competitions
Browse competitions and read their submission specs
Check eligibility before submitting
Submit competition entries (cheatsheet, model-reference, solver-participation, IGP24-polynomial)
View leaderboards and your own standing
Read, download, and manage submissions
Track IGP24 label discovery progress in bulk
Playground
Browse available models and problem sets for practice
Submit, list, cancel, and manage practice runs
Retrieve per-problem results for a run
Stream live verdict events for solver-participation runs
Check usage and credit balance
Cheatsheets
Create, list, read, update, and delete personal cheatsheets for use in runs and competitions
Solver Templates
Create, list, read, update, and delete personal Lean 4 solver templates
Custom Lean Problems
Create, list, read, and delete private immutable Lean statement pairs for use in solver-participation runs
Contributor Network
Browse and search shared cheatsheets, solver templates, and model references
Publish and withdraw your own resources to/from the community
Favorite and unfavorite items
Comment on items and delete your own comments
Explore lineage graphs for individual items or across all visible items
View benchmark results for published items, overall or per-model
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@SAIR MCP Server List all active competitions"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Sign in to SAIR and open Account settings -> API keys.
Create a key and select the scopes you need. At minimum, for the examples below:
competition.readandcompetition.write. Addplayground.read/playground.writefor Playground tools,contributor-network.read/contributor-network.writefor Contributor Network tools.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 |
| Yes | - | Your personal SAIR API key. The server refuses to start without it. |
| No |
| Override for testing against a different environment. |
Running it standalone
python -m sair_mcpThis 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-mcpNo 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:
get_me-- confirm the key is valid and see its scopes.list_competitions-- find a competition ID.get_competition("modular-arithmetic-challenge")-- readsubmissionSpecto learn the requiredpayloadshape.get_my_participation("modular-arithmetic-challenge")-- checkcanSubmitbefore attempting anything.submit_competition_entry("modular-arithmetic-challenge", payload={"modelName": "you/your-model", "commitHash": "0123...(40 hex chars)"}).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 |
| none | Confirm the API key and see its owner + granted scopes. |
Competitions (10 tools)
Tool | Scope | Purpose |
|
| List competitions visible through the API. |
|
| Get one competition's detail and |
|
| Check |
|
| List published leaderboard rows. |
|
| Get the caller's own leaderboard entry. |
|
| Create or replace the caller's submission. |
|
| Read the caller's current submission (or history, for IGP24). |
|
| Read one submission by ID. |
|
| Download the stored text body of a submission. |
|
| Bulk aggregate IGP24 discovery progress by label. |
Playground (10 tools)
Tool | Scope | Purpose |
|
| List model IDs accepted in runs for a competition. |
|
| List available practice problem sets. |
|
| Get every problem in one problem set. |
|
| Create a practice run. |
|
| List the caller's runs for a competition. |
|
| Get one run's params, summary, and timing. |
|
| Cancel a pending/running run. |
|
| List per-cell/per-problem result rows for a run. |
|
| Collect live verdict events for a solver-participation run (blocks up to a timeout). |
|
| Get the caller's practice credit/usage counters. |
Cheatsheets (5 tools)
Tool | Scope | Purpose |
|
| List the caller's cheatsheets. |
|
| Get one cheatsheet including its content. |
|
| Create a cheatsheet. |
|
| Update a cheatsheet's title/content. |
|
| Delete a cheatsheet. |
Solver templates (5 tools)
Tool | Scope | Purpose |
|
| List the caller's Lean solver templates. |
|
| Get one solver template including its source. |
|
| Create a solver template. |
|
| Update a solver template's title/source. |
|
| Delete a solver template. |
Custom Lean problems (4 tools)
Tool | Scope | Purpose |
|
| List the caller's private Lean statement pairs. |
|
| Get one custom problem. |
|
| Create an immutable custom Lean problem. |
|
| Delete a custom problem. |
Contributor Network (13 tools)
Tool | Scope | Purpose |
|
| Browse shared cheatsheets/solver templates/model references. |
|
| Get one item's full payload. |
|
| Publish a saved resource, submission body, inline text, or model reference. |
|
| Withdraw (unpublish) an item you authored. |
|
| Favorite an item. |
|
| Unfavorite an item. |
|
| List comments on an item. |
|
| Post a comment. |
|
| Delete a comment. |
|
| Get the lineage subgraph rooted at one item. |
|
| Get the lineage graph across all visible items. |
|
| List platform-run benchmark summaries. |
|
| Get the per-model benchmark breakdown for one item. |
Total: 48 tools.
Development
pip install -e ".[dev]"
pytest --cov=sair_mcp --cov-report=term-missingAll 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 toolscancel_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
Scored across 48 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for interacting with the Supabase platform
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
Hosted MCP server for live public-data APIs and Skills for AI agents.
The official MCP Server for the Mux API
Related MCP Servers
- AlicenseAqualityCmaintenanceA 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.42127 npm13MIT
- AlicenseBqualityDmaintenanceMCP 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.1628 PyPIMIT
- AlicenseBqualityDmaintenanceA full-featured MCP server for the Kaggle API — competitions, datasets, kernels, models, benchmarks, and discussions.5188 PyPI4MIT
- FlicenseNot gradedqualityDmaintenanceLocal MCP server that exposes fixed tools for GPT, Claude, and Gemini while routing to any OpenAI-compatible chat completions backend with independent configuration per target.1-