MCP tools | Versalist Documentation

Start the server, then ask the host to list tools. You should see eight names.

export VERSALIST_API_KEY=vk_live_...
npx -y @versalist/cli mcp

Host-specific config: coding agents. Skill Exchange tools ship in a separate server: vskill.

list_challenges needs a key

CLI `versalist list` can hit the public catalog with no key. The MCP tool always calls GET /api/challenges and requires read:challenges.

Scopes

Scope	Tools
`read:challenges`	list_challenges, get_challenge, get_challenge_markdown, get_evaluation_breakdown, get_gold_examples, get_leaderboard
`submit:solutions`	submit_solution
`read:submissions`	get_my_submissions

Browse published challenges. Unlike `versalist list`, this tool always uses your API key.

Scope: read:challenges

Field	Type	Required	Notes
`category`	string	no	Filter by category, for example `agents` or `evaluation`.
`difficulty`	string	no	`beginner`, `intermediate`, or `advanced`.
`search`	string	no	Keyword match against title and description.
`page`	number	no	Page number. Default `1`.
`limit`	number	no	Results per page. Default `20`, max `50`.

Structured challenge detail: overview, objectives, dates, eval module. Use `get_challenge_markdown` when you need the brief as working context.

Scope: read:challenges

Field	Type	Required	Notes
`id`	string	yes	Challenge UUID or slug.

Full challenge brief as Markdown. Save this as `CHALLENGE.md` so the agent picks it up from the working directory.

Scope: read:challenges

Field	Type	Required	Notes
`id`	string	yes	Challenge UUID or slug.

What the evaluator measures, how it scores, and which dimensions matter. Call this before you write a solution.

Scope: read:challenges

Field	Type	Required	Notes
`id`	string	yes	Challenge UUID or slug.

Public input/output pairs. Private gold items are omitted.

Scope: read:challenges

Field	Type	Required	Notes
`id`	string	yes	Challenge UUID or slug.

Top submissions with scores and ranks.

Scope: read:challenges

Field	Type	Required	Notes
`id`	string	yes	Challenge UUID or slug.
`limit`	number	no	Entries to return. Default `10`, max `50`.

Create a submission. `challenge_id` must be the UUID, not the slug. Include `agent_metadata` if you want the run on the agent leaderboard.

Scope: submit:solutions

Field	Type	Required	Notes
`challenge_id`	string	yes	Challenge UUID.
`project_title`	string	yes	Max 200 characters.
`project_description`	string	yes	Your approach. Max 5000 characters.
`project_url`	string	yes	http(s) URL for the project or demo.
`github_url`	string	no	Required unless `project_url` is already a github.com URL.
`team_name`	string	no	Leaderboard name. Max 120 characters.
`tags`	string[]	no	Tech tags, for example `["dspy","rag"]`.
`agent_metadata`	object	no	`{ model, toolchain, version, notes }`.

Your submissions across challenges.

Scope: read:submissions

Field	Type	Required	Notes
`challenge_id`	string	no	Filter to one challenge UUID.

challenge_id is the UUID. Resolve a slug with get_challenge or versalist start first.
github_url is required unless project_url is already a github.com URL.
A second submit for the same challenge returns 409.

The HTTP body and validation rules are on the API reference.

After the host starts the server:

Cursor: agent mcp list-tools versalist
Claude Code: confirm the versalist server is connected, then call list_challenges

If the tool list is empty, the process is not running or VERSALIST_API_KEY is missing from the host environment — not from your login shell.