mindcraft-mcp

The local MCP server of Mindcraft by Latency Labs. It runs on your machine, connects Codex or Claude Code to your Mindcraft account, and starts research campaigns on your own repository. The server holds only your API URL and your personal API token. Every durable decision stays in the Mindcraft API.

Setup

The procedure needs uv. It supplies Python by itself.

1. When uv is not installed, install it: curl -LsSf https://astral.sh/uv/install.sh | sh.
2. Register the server in your client: claude mcp add mindcraft --scope user -- uvx mindcraft-mcp@latest (Codex: codex mcp add mindcraft -- uvx mindcraft-mcp@latest).
3. Ask the client to show your Mindcraft account. On the first call a browser page opens: sign in with Google, then click Connect. The call then answers with your account.

The first call stores the token in ~/.config/mindcraft/credentials.json (mode 0600). If no browser can open (for example over SSH), the call answers with the URL to open on another device; call the tool again after you approved the request. uvx mindcraft-mcp setup does the same sign-in from the terminal and also registers the server in each client that it finds on your PATH. On a machine without a browser, run uvx mindcraft-mcp setup --no-browser, open the URL on another device, and type the code that the page shows. uvx mindcraft-mcp logout revokes the token and deletes the file.

Caution: click Connect only for a command that you started on your own machine.

Your first campaign

This is the path from an empty machine to a measured model. It works for any account, any budget and any repository that has the Mindcraft layout (setup/ and eval/; uvx mindcraft-mcp has an inspect tool that tells you what is missing). An operator of the platform sets the budget; everything else is yours.

1. Budget. Ask your operator for a campaign ceiling on your account. The operator sets it by your email address on the operator website, also before your first sign-in. Without a ceiling, the checks stop with LIMIT_REQUIRED. The ceiling, times nothing, is the most a campaign can cost you: the price is the recorded cost × 1.1, and the platform stops the run when it reaches the limit. A campaign can carry a lower limit of its own (campaign_limit_usd at creation).
2. Install. claude mcp add mindcraft --scope user -- uvx mindcraft-mcp@latest (Codex: codex mcp add mindcraft -- uvx mindcraft-mcp@latest). Check with claude mcp list: mindcraft … Connected. No browser opens yet.
3. Sign in. Ask the client: "Show my Mindcraft account." A browser page opens: sign in with Google and click Connect. The answer shows your email, your ceiling, your model keys and the names of your secrets. The token is stored in ~/.config/mindcraft/credentials.json (mode 0600). Without a browser, the answer shows a URL to open on another device; then ask again.
4. Secrets and keys. On the website, /settings/secrets holds the values your training needs (for example HF_TOKEN, WANDB_API_KEY): saved once, never shown again, given only to the campaigns that name them. /settings/connections holds your model keys and the GitHub connection for private repositories.
5. Inspect. "Inspect this repository with mindcraft" (a local path or a GitHub reference). You get the layout, static and hardware checks, the objectives and a list of what is missing. Fix the findings before you create.
6. Create and start. "Create a campaign for it with the compute of setup/compute.json, give it the secrets HF_TOKEN, run the checks and start it." The reply names the run page (https://mindcraft.latencylabs.ai/runs/<id>): the chosen GPU class with its estimated cost and confidence, the price line against your limit, and the checks. A placement that finds no offer answers PLACEMENT_NONE with the reasons.
7. Steer and watch. "What is the status?", "Give the direction: try a smaller decoder", "Stop the campaign". The run page shows the price, the experiments and their measurements. A campaign with eval/latency.toml gets a trained latency measurement on a device and, with the engine scripts, an engine accuracy record; the final measurement runs when the campaign ends, within its two-hour deadline.
8. Tokens. /settings/tokens lists every MCP token; revoke one there or run uvx mindcraft-mcp logout. The next call signs in again.

Tools

Each result has a link to the run page on https://mindcraft.latencylabs.ai.

Settings

The repository that a run uses must follow the Mindcraft repository contract; the Mindcraft documentation describes it.