MCP server

Anvil has a Model Context Protocol server, so a coding agent such as Claude Code, Codex, Cursor or VS Code can set Anvil up for a repository, check on CI and reviews, run and cancel jobs, fix review findings and start Anvil's own agent tasks, all from the terminal or editor.

To connect Claude Code, Codex, Cursor or VS Code, follow Connect your agent. This page is the reference: access levels, what agents can do, and every tool.

What the agent may do #

On the consent screen you choose one of three levels. Each tool needs one of them, listed in the reference below.

Whatever the level, the agent acts as you: it sees only the repositories you can see, and the git host still checks your own permissions, so it can't push where you can't. A tool that needs more than the connection has returns an error saying which level to allow.

Connected agents are listed in Settings → Connect an agent with their level and when they were last used. Disconnect ends their access at once. Agents stay signed in by refreshing a short-lived access token (one hour) with a refresh token (30 days, replaced on every use), so an agent you stop using drops off on its own.

API tokens #

Where there's no browser (CI jobs, scripts) or the client has no OAuth, send a personal API token from Settings → Connect an agent as Authorization: Bearer $ANVIL_TOKEN. Tokens start with rvw_, carry one of the three levels, and work as the git password for hosted repositories too. Steps in Connect your agent.

What agents can do #

A few typical requests and the tools behind them:

• "What needs my attention?" get_status lists branches with failing CI, open pull requests with unresolved critical or major findings, jobs queued or running, the runner queue, reviews and agent tasks in progress, and this month's spend against your budget.
• "Set up Anvil for this repository." The setup_repository prompt walks the agent through list_github_installations (or create_mirror), set_automatic_reviews, a .anvil.yaml drafted from the codebase (validate_review_config, then write_review_config, which opens a pull request), runner labels (get_runner_guide) and a monitor (set_monitor).
• "Why is CI failing?" list_runs, get_job_logs with a search, search_logs across jobs, list_tests and get_test_history to tell flaky from broken, then rerun with failed_only, or start_agent_task with fix_ci.
• "Fix the review findings." list_findings returns each finding with its index and an agent prompt; the agent fixes them, apply_suggestions commits Anvil's suggestions, dismiss_finding records false positives (optionally as a learning), resolve_finding marks what's fixed, and request_review plus wait_for_review checks the result.
• "Try my tests on Node 24 first." run_workflow sends a workflow and runs it once on a scratch branch anvil-ci/<id>, then wait_for_run waits for it and deletes the branch.

Long operations have wait_for_… tools (wait_for_run, wait_for_review, wait_for_agent_task) that wait up to a timeout and send progress. When one returns "finished": false, the agent calls it again. Every error says what to do next.

Prompts and resources #

The server also offers prompts (in Claude Code, /mcp__anvil__setup_repository and so on): setup_repository, why_is_ci_failing, address_review_findings and status_report. As resources it serves every page of this documentation (anvil://docs/<page>), the JSON Schema of .anvil.yaml (anvil://schema/anvil-yaml), the runner guide (anvil://guide/runners) and this tool reference (anvil://reference/tools).

Example: an agent runs a workflow #

You ask Claude Code: "Check that the test suite passes on Node 24 before I bump the engines field." The agent calls run_workflow:

{
  "repo": "alice/shop",
  "ref": "main",
  "name": "node-24-check",
  "yaml": "jobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: 24\n      - run: npm ci\n      - run: npm test\n"
}

Anvil replaces the workflow's on: trigger so it runs exactly once, commits it as .gitea/workflows/anvil-ci-<id>.yml on a new branch anvil-ci/<id> made from main, and returns the run's id. The agent then calls wait_for_run: it returns the result, every job and step, and the last lines of each failed job's log, and deletes the scratch branch (pass keep_branch: true to keep it). On GitHub, runs-on: anvil-4cpu runs the same workflow on Anvil's machines.

Tool reference #

Your client shows each tool's full input schema. Repositories are owner/repo when hosted on Anvil and github:owner/repo on GitHub.

Overview #

Who you are, what needs attention, open pull requests.

Setup #

Connect repositories, turn reviews on, write .anvil.yaml, SSH keys, runners.

CI #

Runs, jobs, logs, log search, tests and flaky tests, metrics, monitors, the runner queue.

Reviews #

Reviews, findings, suggestions, threads, agent tasks and learnings.

Prompts #

59 tools. Scopes: read (read only), write (read and write), admin (read, write and setup).

Limits #

• Workflows started through MCP run on the same runners and limits as any other job: see Runner sizes and labels.
• Reviews, Ask and agent tasks count against the monthly AI budget of the repository's owner.
• wait_for_… tools wait at most 10 minutes per call; call them again for longer work.
• Dynamic client registration is limited per address; unused registrations are removed after 30 days.