The Vera MCP server

Using this from Claude Code? The Vera plugin wraps this surface in a skill plus /vera:verify, /vera:cover, /vera:fix, /vera:repro, /vera:check and /vera:status, so the procedure does not have to be re-explained each session.

Vera exposes its projects, tests, runs, and AI repair/generation as an MCP server so any MCP client — Claude Code, Claude Desktop, another agent — can drive Vera directly: run a test, read why it failed, propose a fix, apply it (with your approval), and re-run. This is the practical "self-fixing" loop: point your coding agent at both your app's repo and Vera, and it can close the loop from a failing test to a green one.

• Endpoint: POST /api/mcp (Streamable HTTP, stateless — no session to manage).
• Auth: a vera_… bearer token (the same tokens the CI API uses), scoped to your organization and fenced to /api/mcp.
• Isolation: every tool is org-scoped by the token — a token for org A can never see or touch org B's data.

1. Mint a token

In the dashboard: Settings → CI Tokens → name it → Create. Optionally set an expiry; leave org-wide unchecked for a personal token (audit rows and usage counters then name a human rather than a shared actor).

The plaintext token (vera_…) is shown once — copy it now. Revoking it in the dashboard takes effect immediately (the next MCP call with it returns 401), and so does an expiry passing.

Plans: the MCP surface is the free tier's floor (mcp-basic), so a free cloud workspace can mint a token and use it here. The /api/v1 CI surface is separate and needs Pro (api-access) — the same token, fenced by URL. Self-hosted installs have no billing and hold everything.

2. Point your client at it

Claude Code (recommended): let vera-agent init do it

npx vera-agent init --url https://your-vera-host --token vera_your_token

This registers a vera HTTP MCP server for the repo you run it in — along with linking the repo to a project and writing the agent-instructions block. See Getting started for the whole flow, including the .vera/config.json (committed) vs ~/.vera/cli.json (token, chmod 600) split.

Two registration scopes:

• --mcp-scope local (default) — claude mcp add at local scope. That entry lives in ~/.claude.json, private to you and outside the repo, so it carries the real token and needs nothing else set up.
• --mcp-scope project — merges a vera entry into the repo's committed .mcp.json, so everyone who clones gets the tools. The entry carries the literal ${VERA_TOKEN}, never a secret; each developer exports their own (export VERA_TOKEN=vera_…). Claude Code asks once to approve a project-scope server before connecting.

init never clobbers: it only ever touches the vera key under mcpServers, leaves every other server alone, refuses (rather than overwrites) a .mcp.json it cannot parse, and reports "already up to date" on a re-run. If a vera server is already registered in any scope, it leaves it as it is and tells you the fix-it (claude mcp remove vera, then re-run).

Already using the Vera plugin? It ships its own vera server entry driven by VERA_MCP_URL + VERA_TOKEN — you don't need both, so run init --no-mcp and set those two variables instead.

Manual — other MCP clients, or no claude CLI

init prints this command when the claude CLI isn't on PATH:

claude mcp add --transport http vera https://your-vera-host/api/mcp \
  --header "Authorization: Bearer vera_your_token"

Or write the config by hand — a project .mcp.json, or Claude Desktop's MCP config, or any other Streamable-HTTP MCP client:

{
  "mcpServers": {
    "vera": {
      "type": "http",
      "url": "https://your-vera-host/api/mcp",
      "headers": {
        "Authorization": "Bearer vera_your_token_here"
      }
    }
  }
}

For a local server the URL is http://localhost:4545/api/mcp. In a committed file use "Bearer ${VERA_TOKEN}" and export the token in your environment. Restart the client and the vera tools appear.

3. Tools

Read-only:

source — who wrote the test. list_tests and get_test report it: manual (a person, in the builder or through an importer), ai (Vera's generators, including an AI-assisted import), mcp (created or edited through these tools), or absent for a row created before Vera recorded provenance, or holding a value this build does not recognise. Absent means not stated — never assume manual. It is also not a review signal: a test can be ai and approved, or manual and never looked at by anyone but its author. recorded is defined but nothing writes it today, so a test captured in the recorder reports manual.

Actions:

Intent blocks

An intent block keeps the goal of a stretch of steps next to the steps that achieve it. It opens with an intent step and closes with end-intent:

[
  { "id": "s1", "action": "goto", "url": "/login" },
  { "id": "s2", "action": "intent", "goal": "Sign in as the demo user", "values": ["email", "password"] },
  { "id": "s3", "action": "fill", "selector": "#email", "value": "{{email}}" },
  { "id": "s4", "action": "fill", "selector": "#password", "value": "{{password}}" },
  { "id": "s5", "action": "click", "selector": "button[type=submit]" },
  { "id": "s6", "action": "end-intent" },
  { "id": "s7", "action": "assert", "assertType": "url", "condition": "contains", "value": "/dashboard" }
]

• goal is free text (up to 500 characters). values lists the names of the variables the goal may type (email, never {{email}} and never a value).
• Blocks must balance and cannot nest; an if or loop inside one is fine. create_test and update_test_steps refuse an unclosed, stray or nested block with the step schema's own message, and save nothing.
• Every run replays the steps between the markers as ordinary steps. When they break (or the block has none yet), a model may re-derive them from the goal in exactly two places: an explicit resolve (POST /api/tests/:id/resolve, which runs the test once on the cloud with the block allowed to resolve) and the repair ladder's self-heal re-run (the gardener, or Auto-repair on a failed run). Every other run — the builder's Run, CI, scheduled, MCP run_test and vera-agent — replays only, never calls a model, and fails the step intent-stale.
• A resolution chooses each action from the controls on the live page first (TypeSafe, when enabled for the workspace) and asks your AI model only when that cannot decide. It may only drive the page on the project's own origin, and it types nothing but the block's declared values, by name. Both are plan-gated like auto-repair.
• A resolution is saved into the block only when the run confirmed it: the block did what it did on its last green run, or an outcome assertion after end-intent passed. Then the steps that broke are replaced with the ones that worked, as a repair with strategy intent that Revert undoes. Anything else is staged in Staged repairs for review. The resolve call answers with the run plus resolution: { outcome: "written" | "proposed" | "none", steps?, proposalId?, reason? }. Once saved, every later run replays the new steps with no model call.
• Follow each block with an assertion that proves its outcome. Without one the block can never be verified, and the assertion lint says so.

Journeys, chains and Actor Scenarios

Three words that are easy to cross, so here is what each one is and which tool makes it:

Build bottom-up: create_test for each leg, list_project_roles for the role ids, then create_chain or create_scenario over those tests, then create_journey + update_journey { linkedTestIds } so the coverage map shows what now protects the flow.

Two things are stricter here than in the dashboard, because the caller types ids instead of picking them from a list: every project, test and flow a definition names must exist in your workspace in the project the definition says (code: "unresolved_references", nothing saved), and a stage's inline steps must pass the step schema.

Running one. run_actor_scenario { scenarioId } returns { scenarioRunId } immediately; poll get_scenario_run (a timeline plus per-actor lanes, status: "running" until it ends) and stop it with cancel_run { kind: "scenario" }. resumeFrom keeps an earlier run's passed stages. It needs scenarios:run rather than tests:run — the permission exists so a workspace can withhold "drive several personas across projects". MCP tokens carry it, but a personal token is always intersected with its owner's current role, so a member whose role lacks scenarios:run does not see the tool.

check_coverage — a pointer, not a pipeline

check_coverage is the agent-facing half of vera check. It reports: it runs no test, generates nothing, and writes nothing. What it adds on top of the report is nextActions — one suggestion per finding, with the arguments already filled in (run_test for the impacted set, run_scenario for what nothing maps to, generate_tests for the gaps, carrying the ruleIds that make the result count as coverage next time). It makes none of those calls itself, deliberately: chaining a metered generation off a heuristic's guess is not something a tool named "check" should do on its own.

Four things it refuses to blur:

• gaps vs partial. A gap is a touched rule with no adequate protection (uncovered / insensitive). partial is a rule that does have a covering test whose assertions were never proven sensitive to it — a weaker claim, not a failure. A sensitive verdict requires a dataset, so treating partial as a gap would paint every healthy project red. vera check --strict never fails on partial.
• impactedTests vs alwaysRunTests. The tag join is reported in its own key, so "the map found these" stays distinguishable from "you told me to always run these".
• Evidence confidence. high = a framework route file (Next app/pages, SvelteKit, Remix, Express) or a rule's own file:line. low = a route inferred from a filename — a guess. Each impacted test also carries a rolled-up high / mixed / guess-only.
• Cold start. On a project whose tests carry no URLs and no rule links, coldStart.cold is true and coldStartFix names the single command that fixes it. An empty report on a cold project means the map is blind, not that the change is safe.

Bounds behave exactly as on the HTTP route, and all of them are reported (never silent): over 5000 paths or a path over 500 characters is a refusal (too_many_changed_files / path_too_long, nothing computed); list caps and the 25-line-per-item evidence cap truncate and say so in truncated[] / evidenceTruncated / warnings. One difference worth knowing: /api/mcp carries a single JSON-RPC body limit for every tool (1 MiB by default) where the HTTP impact route allows 4 MiB — the effective number comes back in bounds.maxRequestBodyBytes.

get_app_changes — read state before you read the list

check_coverage answers "I changed these files"; get_app_changes answers the other direction — the app changed and nobody told you. The radar re-fingerprints the project's pages on a cadence (structure only: tag/type/role/name/data-testid/id, never copy, so a wording change is not a change) and every difference from the accepted baseline becomes one row. Each row names the URL, the element-level diff, and impactedTests — the tests that click a moved element or navigate to the changed page. That last field is the reason to call it.

An empty list is two different answers, and state is which one:

Dispositions are not symmetric, and neither the tool nor the dashboard presents them as two equal buttons:

• expected — intended. Accepting advances the fingerprint baseline, so the row leaves the queue and that diff never fires again. This is the only way the feed reaches zero.
• suspect — a possible regression. The row stays open and the baseline does not move, on purpose. Marking suspect is not a way to clear the feed.

The tool is read-only: it sets no disposition (that is the project's Radar panel, or POST /api/radar/changes/:id/disposition) and, unlike the HTTP GET, it never creates a radar row as a side effect. Bounds are reported, never silent: at most 50 rows (limit, with notShown when the feed is longer), 10 impacted tests and 10 elements per row (each list carries its own notShown), plus any warnings the sweep recorded. An invalid since is refused (invalid_since) rather than silently compared as a string, which would return a plausible but wrong window.

The confirm-to-apply rule

Vera never rewrites a test or mutates an issue without explicit approval. apply_repair, update_test_steps, and update_issue all refuse unless you pass confirm: true — call once to review, then again with confirm: true to persist. The typical repair loop:

run_test → (failed) → get_failure_details → suggest_fix
  → review the operations → apply_repair(confirm: true) → run_test → green

When a green fix can't be found, close the loop by filing a tracked issue instead of leaving the failure to rot:

run_test → (failed) → get_failure_details → suggest_fix
  → apply_repair(confirm: true) → run_test → (still failing)
  → report_issue(testId, runId, severity: 'major')

4. Permissions & limits

• A token grants the MCP surface projects:read, tests:read, tests:run, runs:read, issues:read, issues:manage, ai:use (the AI tools), and the authoring grants tests:manage + flows:manage. It cannot read or change organization or platform settings, and it can never create a project. The same token on /api/v1 carries a narrower set — no ai:use, no flows:manage (it does hold tests:manage, which is what the CI importer route needs).
• Tool availability follows the token's permissions: list_issues appears only with issues:read; report_issue / update_issue only with issues:manage; create_test / update_test_steps with tests:manage; create_flow / update_flow / delete_flow with flows:manage; check_coverage and get_app_changes with tests:read (the same grant their HTTP twins require).
• Plan-gated tools mirror their HTTP twin's entitlement and return the same 403 payload (code, plan, feature, requiredPlan) as a tool error rather than a re-phrasing: get_app_changes needs Pro+ (app-radar); list_chains / run_chain need Team+ (chains).
• AI tools (suggest_fix, apply_repair proposals, generate_tests, generate_repro_test) are metered to your org's AI usage/budget, exactly like the dashboard. check_coverage, get_app_changes and inspect_page are not: they call no model.
• The endpoint is covered by the same per-org rate limit as the rest of the API (QA_RATE_LIMIT_PER_MIN, off by default in local dev).

See also

• Getting started — npx vera-agent init: link the repo, register this server, and the ritual the tools exist for.
• The Vera Claude Code plugin — the skill and /vera:* commands wrapped around these tools.
• The local agent — running the browser on your own machine, which is what makes localhost testable (scenario_cloud_only's fix).