MCP setup: Karts docs

karts mcp runs an MCP server on stdio. It offers the environment commands as tools, so your agent can build its branch, run tests inside the VM and read logs without parsing terminal output. It uses the token from karts login, or KARTS_TOKEN if set.

Sign in first with karts login, and run karts init in the repository. Make sure karts is on the PATH your agent sees.

Claude Code

claude mcp add karts -- karts mcp

Or share it with everyone on the repository by adding it to .mcp.json at the top of the repository:

{
  "mcpServers": {
    "karts": { "command": "karts", "args": ["mcp"] }
  }
}

Codex

codex mcp add karts -- karts mcp

Or add it to ~/.codex/config.toml yourself:

[mcp_servers.karts]
command = "karts"
args = ["mcp"]

Cursor

Add it to .cursor/mcp.json in the repository, or to ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "karts": { "command": "karts", "args": ["mcp"] }
  }
}

Tools

Tool	What it does
`up`	Builds this branch in a fresh micro-VM with its own migrated, seeded Postgres and serves it at a public URL (seed data only). A repeat call builds a new revision and switches when it is ready; no database rows carry over. Takes the same options as `karts up`.
`down`	Tears the environment down: its VM and database are destroyed.
`status`	The environment's state, URL, revisions and warnings.
`logs`	The environment's logs (app, install, migrations, seed). Takes `revision` and `tail`.
`exec`	Runs a command inside the environment's VM, with `DATABASE_URL` set, and returns its output and exit code.
`check_config`	Checks `karts.yml` and the files `karts up` would upload, locally, as karts check-config does, and returns its JSON. No sign-in needed.

Every tool takes an optional dir, the repository directory, which defaults to the directory karts mcp started in.

Telling your agent when to use it

A line in your agent's instructions file (CLAUDE.md, AGENTS.md or Cursor rules) helps:

Before you say a change works, run the karts "up" tool on this branch,
run the tests with the "exec" tool, and open the URL it returns.