The Prufa MCP server provides a comprehensive suite of tools for web application QA, enabling agents to audit, monitor, and manage web application health.
Audit & Reporting: Run one-shot QA audits on public URLs to detect broken flows, console errors, tracking failures, consent violations, security headers issues, mobile tap targets, and accessibility problems. Supports blocking mode (waits and returns findings directly) and non-blocking mode (returns a run_id for later polling). Fetch completed reports by run UUID or share token, retrieving structured JSON with findings grouped into graded sections (A–F), each with severity, impact, and fix hints. List recent runs, alerts, and findings.
Workspace & Usage Management: Create free trial workspaces, retrieve workspace details and usage/credits, configure settings and notification preferences (email/Slack).
Billing: Access Stripe checkout for upgrading plans or buying credits, and manage subscriptions via the Stripe customer portal.
Flows: Create, confirm, run, edit, list, and delete multi-step user journeys defined as plain text, including setting credentials for execution.
Monitors: Set up monitors to watch URLs or flows on a schedule, trigger on demand, pause/resume, and manage deploy-hook secrets.
Gremlin (Chaos QA): Run chaos tests imitating difficult users, rerun past tests, authorize domains for mutation, and promote reproduced bug paths into draft flows.
Discovery: Register and verify domains via DNS, crawl them to automatically draft meaningful user flows, and retrieve discovery run statuses.
CI Integration: Generate a GitHub Action template to fail PRs on critical regressions.
Health Check: Probe the server and API for health status.
Vibe-coded apps ship faster than anyone can review them. In June 2026 we audited 49 fresh Show HN launches — 38 had a critical bug on day one: a broken signup, a silent console error, analytics that never fired, a consent banner that did nothing.
Prufa is the agent that catches those before your users do. Point it at a URL and it audits the things humans skip when they're moving fast — broken flows, JS console errors, missing tracking, consent violations, security headers, mobile tap targets, accessibility — and hands back machine-verified findings, graded A–F. This repo is the open-source MCP server that wires that audit straight into your coding agent.
Related MCP server: Argus
Ask your agent to audit https://yourapp.com and prufa_run_audit returns one
JSON report. Findings are grouped into graded sections, each finding carries a
severity, the impact (why it matters), and a fix hint. Real output,
trimmed:
{
"url": "https://yourapp.com",
"headline": "2 warnings found",
"counts": { "critical": 0, "warning": 2, "info": 5 },
"sections": [
{ "label": "Works", "grade": "C", "counts": { "warning": 2, "info": 1 } },
{ "label": "Fast", "grade": "A" },
{ "label": "Found", "grade": "A" },
{ "label": "Compliant", "grade": "A" }
],
"check_results": [
{
"check_id": "ux",
"findings": [{
"severity": "warning",
"title": "2 javascript console error(s) during page load",
"impact": "Errors at load time often mean broken features visitors never report.",
"evidence": { "count": 2, "sample": [
"Access to XMLHttpRequest at 'https://api.fontshare.com/...' blocked by CORS policy",
"Failed to load resource: net::ERR_FAILED"
]}
}]
},
{
"check_id": "mobile",
"findings": [{
"severity": "warning",
"title": "13 tap target(s) smaller than 24px",
"impact": "Fingers are not cursors — undersized buttons mean mis-taps on exactly the elements you want pressed.",
"fix_hint": "Give interactive elements at least 24x24px of hit area (WCAG 2.5.8)."
}]
},
{
"check_id": "security",
"findings": [{
"severity": "info",
"title": "no Content-Security-Policy header",
"impact": "Without a CSP, one injected script owns the page — and every third-party tag you load is trusted completely.",
"fix_hint": "Start with a report-only CSP and tighten from real violation reports."
}]
}
],
"report_url": "/r/G82RpzTi_zn-o71_XoMLCprP7uvCQP87"
}report_url is a shareable HTML version of the same report. The full payload
also includes tracking, consent, seo/aeo, a11y, forms, and detected
user flows — see the OSS surface below.
The package is on PyPI. Install it
globally with pipx (recommended — isolated venv, exposes the prufa-mcp
binary on your PATH) or into a project venv with pip:
# Recommended — global install, isolated venv
pipx install prufa-mcp
# Or, into your project venv
pip install prufa-mcp
# Pin a specific version with ==, e.g. pipx install prufa-mcp==0.1.3
# Verify the binary is on PATH
which prufa-mcp
# Should print something like: /Users/you/.local/bin/prufa-mcpYou also need a free Prufa API key. The first audit is free, no card required.
Sign in at prufa.dev (Google OAuth)
Create an API key from the dashboard
The MCP server runs as a stdio subprocess, spawned by your agent on first use.
The cleanest way to register it is claude mcp add (Claude Code's built-in
command — it writes the config to ~/.claude.json correctly, which the
~/.claude/mcp.json path does NOT).
# Get the absolute path of the binary (use whatever `which prufa-mcp` returned)
PRUFA_BIN=$(which prufa-mcp)
# Add the MCP server. The token stays out of your shell history.
read -s -p "Prufa API token: " PRUFA_TOKEN && echo
claude mcp add \
--scope user \
--env "PRUFA_API_TOKEN=$PRUFA_TOKEN" \
prufa \
-- "$PRUFA_BIN"Restart Claude Code (config is read at startup), then verify:
/mcpYou should see prufa listed as Connected, with prufa_run_audit and
prufa_get_report as available tools.
.mcp.json)In your project root or in ~/.config/Claude/ etc.:
{
"mcpServers": {
"prufa": {
"command": "/Users/you/.local/bin/prufa-mcp",
"env": {
"PRUFA_API_TOKEN": "your-prufa-api-key"
}
}
}
}Restart the host app. The command path must be the absolute binary path
(not ~, not $()) — those don't expand in MCP config.
Prefer config files to env vars? Drop your token in
~/.config/prufa/mcp.jsoninstead — see ADVANCED.md.
In your agent:
> audit https://my-vibe-coded-app.com and show me the criticals
> run prufa on my staging deploy
> fetch the report for the audit I just ranprufa_run_audit with wait=true (the default) blocks until the audit
completes and returns the JSON report directly — typically 25–60s for a public
page. If you set wait=false, the call returns immediately with the queued
state plus a share_token you can poll with prufa_get_report.
prufa-mcp exposes the whole product over MCP (44 tools). Point your agent
at Prufa and it can audit pages, drive multi-step flows, watch for regressions,
run chaos tests, run full-auto discovery, and manage the workspace + billing —
no dashboard round-trip. Free/anonymous tools need no card; Pro tools return the
API's 402 with a checkout link when you're not on a plan (the tool is visible,
the paywall is server-side).
Tool | What it does |
| One-shot public-page audit; blocks and returns findings JSON. |
| Fetch a report by UUID or |
| Poll a run's status. |
| Recent runs in the workspace. |
| Persisted findings, machine-readable. |
| Alert ledger (newest first, incl. suppressions). |
Tool | What it does |
| Create a free, no-card |
| Current workspace + inlined usage + a |
| Usage object + |
| Usage webhook, auto-recharge, email/Slack switches. |
| The 9-event × {email, slack} routing matrix. |
Tool | What it does |
| Stripe checkout URL for a paid plan (starter/pro/team). |
| Stripe checkout URL for a one-time credit pack. |
| Stripe customer portal URL (card, invoices, cancel). |
Tool | What it does |
| Compile a plain-text test case to a draft spec. |
| Approve a draft — only confirmed flows run. |
| Execute a confirmed flow. |
| Store |
| Edit the spec (returns it to draft). |
| Read · list · remove. |
Tool | What it does |
| 1-click monitor; returns a deploy-hook secret once. |
| Run now (rate-capped). |
| Lifecycle. |
| Rotate the deploy-hook secret. |
| Deploy-hook delivery log + CI snippets. |
Tool | What it does |
| Imitate a difficult user; detectors verify what breaks. Mutations dry-run unless authorized; payments never execute. |
| Re-run a past gremlin with the same intent + saved login. |
| Allow real (non-payment) writes on a host you own. |
| List mutation authorizations. |
| Reuse a prior login (owning workspace only — sensitive). |
| Turn a reproduced bug path into a draft flow. |
Tool | What it does |
| Register a domain, get the DNS TXT record to publish. |
| Verify the DNS proof. |
| Manage authorized domains. |
| Crawl a verified site and draft its meaningful flows. |
| Run status + the flows it surfaced. |
Plus prufa_health_check() (probe the server/API).
prufa_setup_workspace mints a free agent_temp workspace: no card, a 7-day
trial, and an included credit budget. Monitors, discovery, and full-length
gremlin runs work during the trial, then need a paid plan.
The MCP makes this legible to your agent: prufa_get_usage, prufa_setup_workspace,
and every metered result carry a trial block (days + credits remaining) and,
when you're low on credits or near the trial's end, an upsell block with a
message_for_human your agent can relay plus the exact tool to call
(prufa_upgrade_plan / prufa_buy_credits). When a Pro tool is called off-plan,
the 402 passes through with a checkout_url — no silent failures, no surprise
charges.
Three runnable scripts in examples/:
examples/nextjs-app/ — audit a deployed Next.js app
examples/vite-spa/ — audit a Vite SPA (focuses on client-side routing audits)
examples/stripe-checkout/ — audit a Stripe-checkout page (payment-flow verification)
Each is a copy-pasteable demo:
export PRUFA_API_TOKEN=...
python examples/nextjs-app/audit.py https://your-nextjs-app.comFail a PR when Prufa finds a critical regression:
# .github/workflows/prufa-scan.yml
name: Prufa scan
on: [pull_request]
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.11"
- run: pip install prufa-mcp
- name: Run audit
env:
PRUFA_API_TOKEN: ${{ secrets.PRUFA_API_TOKEN }}
run: |
python -c "
import asyncio, sys
from prufa_mcp.audit import run_audit
report = asyncio.run(run_audit(url='${{ secrets.STAGING_URL }}', wait=True))
print(report.get('headline', 'audit complete'))
criticals = report.get('counts', {}).get('critical', 0)
if criticals:
print(f'::error::Prufa found {criticals} critical finding(s)', file=sys.stderr)
sys.exit(1)
"See examples/prufa-scan.yml for the full template.
Apache-2.0. See LICENSE. Contributions welcome — see CONTRIBUTING.md.
Authorize REAL (non-payment) mutations for the gremlin on a host you own or a staging host — logging in and writing on that host stop being dry-run. Set allow_mutation=false to revoke. This is the gremlin mutation opt-in, NOT the discovery DNS-domain verification (a different system). host is a bare hostname (e.g. staging.acme.com). [Pro]
Inputs: host (required), note, allow_mutation.
Open the Stripe customer portal for this workspace. Returns a portal_url the HUMAN opens to manage the subscription, update the card, or view invoices. A workspace with no Stripe customer yet returns 409 no_stripe_customer (pass that back to the human — they must subscribe first via prufa_upgrade_plan). Mutating + idempotent. [Pro]
Inputs: return_url, idempotency_key.
Buy a one-time prepaid credit pack for this workspace (no subscription change). Returns a Stripe checkout_url the HUMAN opens to pay by card. Use when the workspace is low on credits but you don't want to change the plan. Mutating + idempotent. [Pro]
Inputs: credits (required), cancel_url, success_url, idempotency_key.
Confirm a DRAFT flow so it becomes runnable — only confirmed flows run. Pass flow_id. Optionally pass a corrected spec object to override the compiled draft before confirming (omit it to confirm the draft as-is). Idempotent.
Inputs: flow_id (required), spec, idempotency_key.
Compile a plain-language test case into a reviewable DRAFT flow spec. Pass the target url and a plain-text test_case (e.g. 'log in, add the first product to the cart, and check out'); optionally a name. Returns a 201 draft: the compiled step spec plus any {{VARIABLES}} it detected (logins, coupon codes) and a review instruction. The flow does NOT run yet — review the draft, then call prufa_confirm_flow. Only confirmed flows run. Idempotent.
Inputs: url (required), test_case (required), name, idempotency_key.
Delete a flow by id. NOTE: a flow still used by a monitor returns 409 flow_in_use — pause or delete that monitor first, then retry. Idempotent.
Inputs: flow_id (required), idempotency_key.
Delete a monitor (stops all future runs and revokes its deploy hook). Past run history is retained. Idempotent. [Pro]
Inputs: monitor_id (required), idempotency_key.
Replace a flow's spec. Pass flow_id and the full spec object. NOTE: any edit returns the flow to DRAFT — you must call prufa_confirm_flow again before it can run. Idempotent.
Inputs: spec (required), flow_id (required), idempotency_key.
[Pro] Get a discovery run's status and the draft/advisory flows it surfaced (name, kind, entry_url, status, flow_id, eval_score, detail, confirm_url). Confirm a draft flow (prufa_confirm_flow) to make it runnable.
Inputs: discovery_id (required).
Get the persisted findings for a run (flat, machine-readable). Pass finding_key to filter to a single finding.
Inputs: run_id (required), finding_key.
Get a single flow by id: its compiled spec, status (draft|confirmed), and the NAMES of any stored credentials (never their values).
Inputs: flow_id (required).
Get one monitor's config + latest state (status, cadence, last run, deploy-hook metadata). [Pro]
Inputs: monitor_id (required).
Get the JSON report for a run. Accepts EITHER run_id (UUID from audit creation) OR share_token (the slug after /r/ in report_url). The share_token form is the recommended call shape — it is what the audit creation response returns.
Inputs: run_id, share_token.
Get a run's status by id (queued|running|succeeded|failed|blocked|timeout).
Inputs: run_id (required).
Get this workspace's credit usage (available/included) plus trial state and, when relevant, an upsell block. Use before a costly run to check the balance and relay the message_for_human if credits are low.
Inputs: no named parameters.
Get the current workspace: tier, usage/credits, and trial state (days remaining, what gets gated when the trial ends). Includes an upsell block when the workspace is low on credits or near trial end.
Inputs: no named parameters.
SENSITIVE — returns DECRYPTED email+password for logins previously used by gremlin runs in THIS workspace, so a kickoff can reuse them. Only for the owning workspace. Never print these values into logs, transcripts, or files; pass them straight into prufa_run_gremlin's credentials. [Pro]
Inputs: no named parameters.
Probe the Prufa API and MCP server. Always free, no token required.
Inputs: no named parameters.
Alert history (delta-engine ledger), newest first — includes suppressed alerts with their suppression reason. [Pro]
Inputs: no named parameters.
[Pro] List this workspace's discovery domains with id, domain, status (pending|verified), verified_at, verification_method, test_payments_opt_in, and (for pending domains) the verification TXT record to publish.
Inputs: no named parameters.
List the flows in this workspace with their status (draft|confirmed) and metadata.
Inputs: no named parameters.
List the hosts this workspace has authorized for real gremlin mutations, with each host's allow_mutation flag, note, and created_at, plus the default policy. [Pro]
Inputs: no named parameters.
List a monitor's last 50 deploy-hook deliveries plus copy-paste CI snippets (curl, github_actions, gitlab_ci). never_fired:true powers the 'your webhook never fired' nudge — surface it to the human. [Pro]
Inputs: monitor_id (required).
List every monitor in this workspace. [Pro]
Inputs: no named parameters.
List recent runs in this workspace (auth required).
Inputs: limit.
Pause a monitor — it stops running on its cadence until resumed. History is kept. Idempotent. [Pro]
Inputs: monitor_id (required), idempotency_key.
Import one reproduced gremlin path (by its path_index in the gremlin report) as a DRAFT flow. The flow still needs review + confirmation before it will run — this only creates the draft. Returns flow_id, status='draft', and a review_url. [Pro]
Inputs: path_index (required), share_token (required), idempotency_key.
[Pro] Register a domain for full-auto discovery and get the DNS TXT record to publish. For an unverified domain the response carries a 'verification' object {method, record_name, record_type:'TXT', record_value, hint} — publish that TXT record at your DNS provider, then call prufa_verify_discovery_domain. Set test_payments_opt_in to allow discovery to exercise test-mode payment flows. This DNS-ownership authorization is separate from gremlin mutation opt-in.
Inputs: domain (required), idempotency_key, test_payments_opt_in.
Re-dispatch a past gremlin run with the SAME intent (original url, persona, direction, and saved login) under the current tier's step cap. Returns a NEW run_id. wait=true (default) blocks until the rerun completes and returns the report; wait=false returns the queued state. [Pro]
Inputs: run_id (required), wait, idempotency_key.
Resume a paused monitor. The next scheduled run fires immediately, then it returns to its cadence. Idempotent. [Pro]
Inputs: monitor_id (required), idempotency_key.
[Pro] De-authorize a discovery domain. Future discovery on it is refused and any disposable identities created for it are torn down (the response reports identities_torn_down). Idempotent.
Inputs: domain_id (required), idempotency_key.
Rotate a monitor's deploy-hook signing secret. The new secret is returned ONCE in the response — store it now; the old secret dies immediately, so update your CI before the next delivery. Idempotent. [Pro]
Inputs: monitor_id (required), idempotency_key.
Run a one-shot public-page QA audit on a URL. FREE — no key, no card (runs anonymously; a workspace token, if set, just attributes the run and lifts the per-IP limit). Returns findings JSON (broken flows, JS console errors, tracking/consent, security headers, a11y, mobile) graded A-F. Idempotent. wait=true (default) blocks until the audit completes and returns the report; wait=false returns the queued state with run_id + share_token to poll via prufa_get_report. An anonymous result carries a workspace_unlock block: deeper checks (flows, monitors, discovery, gremlin) need a free workspace (prufa_setup_workspace).
Inputs: url (required), wait.
[Pro] Start a full-auto discovery run on a URL. Crawls the site, infers user flows, and drafts the meaningful ones as reviewable draft flows. Requires a paid/trial tier AND a VERIFIED discovery domain covering the URL's host — otherwise the API returns 403 domain_not_authorized (register + verify the domain first) or 404 if discovery isn't enabled on the deployment. Returns {discovery_id, status, url, result_url}; poll with prufa_get_discovery.
Inputs: url (required), idempotency_key.
Execute a CONFIRMED flow. Returns 202 with run_id + report_url; poll the report via prufa_get_report. Pass per-run credentials as an object mapping the spec's {{VARIABLES}} to values ({'EMAIL': ..., 'PASSWORD': ...}) — these are encrypted in transit and NOT stored (use prufa_set_flow_credentials to store reusable ones). Fails if the flow is still a draft — confirm it first. Idempotent.
Inputs: flow_id (required), credentials, idempotency_key.
Run a gremlin chaos-QA session on a URL: an agent imitates a difficult user (no script) while plain-code detectors verify what breaks. Use to stress-test a real flow beyond the deterministic audit. Mutations are DRY-RUN unless the host is authorized via prufa_authorize_domain; payments are NEVER executed. Optional credentials (a real, non-payment login write) require a signed-in workspace AND mutation authorization for the host. Step budget depends on plan (free teaser 8, Starter 20, Pro 40, Team 60) — call prufa_get_usage for the cap. wait=true (default) blocks until the run completes (can take ~5 min) and returns the report; wait=false returns the queued state with run_id. [Pro]
Inputs: url (required), wait, persona, direction, +2 more.
Store reusable, WRITE-ONLY credentials for a flow so later runs need not resend them. Pass flow_id and a non-empty credentials object mapping the spec's {{VARIABLES}} to values. The response lists the stored variable NAMES only — values are never returned. Idempotent.
Inputs: flow_id (required), credentials (required), idempotency_key.
Set the notification routing matrix: 'cells' is the 9-event x {email, slack} map of booleans deciding which channel each event fires on. The server validates keys and types (422 on unknown/missing keys or non-booleans) and returns {cells, locked_events} (events you can't turn off). [Pro]
Inputs: cells (required).
Bootstrap or read the Prufa workspace this agent uses. If a token is already configured it returns the current workspace (with trial + upsell state). If NO token is set it CREATES a free 'agent_temp' workspace: no card, no charge, a 7-day trial with an included credit budget. During the trial you can run audits, monitors, discovery, and the full gremlin; after it ends monitors/discovery/gremlin_full_run are gated. The 201 response returns an api_token shown ONCE — persist it as PRUFA_API_TOKEN (or in ~/.config/prufa/mcp.json) and re-run with it set. When credits run low or the trial nears its end, tell your human to upgrade (prufa_upgrade_plan) or buy credits (prufa_buy_credits). Idempotent.
Inputs: name, owner_email, idempotency_key.
Start a persistent monitor: re-run a QA audit on a URL on a cadence (daily|hourly) and fire a deploy hook on every regression delta. Pass flow_id to re-run a confirmed flow instead of the plain audit. 1-click setup — the response returns the deploy_hook (url + signing secret, shown ONLY once) which you should store immediately. [Pro] Free-tier workspaces get a 402 with a checkout hint that passes through; do not gate client-side. Idempotent.
Inputs: url (required), cadence, flow_id, idempotency_key.
Trigger a monitor run right now (out of band). Rate-capped to 1 per 60s; if a run is already queued or running the response is deduped (deduped:true) instead of starting a second one. Idempotent. [Pro]
Inputs: monitor_id (required), idempotency_key.
Subscribe or upgrade this workspace to a paid plan (starter | pro | team). Returns a Stripe checkout_url the HUMAN opens in a browser to start the 7-day card-first trial — the agent never enters card details. Mutating + idempotent. [Pro]
Inputs: tier (required), cancel_url, success_url, idempotency_key.
[Pro] Check the published DNS TXT proof for a registered discovery domain now. Idempotent — returns the domain body with status 'verified' once the TXT record resolves, or still 'pending' if DNS hasn't propagated yet (retry later).
Inputs: domain_id (required), idempotency_key.
Update workspace settings — pass only the keys you want to change. Covers display_name, usage webhook (url/secret), overage opt-in, auto_recharge (auto-buys credits when a launch is blocked on an empty balance — needs a card on file), auto_recharge_credits / auto_recharge_monthly_limit_cents, and email/slack alert toggles. At least one setting is required. Idempotent. [Pro]
Inputs: display_name, auto_recharge, idempotency_key, opt_in_to_overage, +6 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 44 tools
Each tool has a clearly distinct purpose with no overlap. For example, prufa_create_flow, prufa_edit_flow, prufa_delete_flow, and prufa_confirm_flow are distinct actions on flows; similarly, prufa_run_audit, prufa_run_discovery, prufa_run_gremlin, and prufa_run_flow target different testing modalities. Monitor and billing tools are also well-separated.
All tool names follow a consistent 'prufa_verb_noun' pattern in snake_case (e.g., prufa_list_flows, prufa_get_flow, prufa_setup_workspace). There is no mixing of styles or ambiguous verbs. The naming convention is predictable and aids tool selection.
With 44 tools, the set is large but justified by the comprehensive nature of the QA platform, covering workspace management, flow lifecycle, monitors, discovery, gremlin testing, billing, and settings. While on the higher end, each tool serves a specific purpose and does not feel excessive for the domain.
The tool surface covers the full lifecycle of testing: workspace setup, flow creation/editing/deletion/confirmation/execution, monitoring with pause/resume/trigger/rotate, discovery with domain registration/verification/revocation, gremlin run/rerun, billing operations, and settings. No obvious gaps for the intended use case.
Website checker for AI coding agents. Measures your site in a real browser, with evidence.
Read-only web QA agent: scans a site in a real browser and returns evidence-backed findings
AI QA tester — real browsers scan sites for bugs, SEO, perf, and accessibility issues via chat.
Browser-based QA for AI-built software. Test pages with real browsers via agents.
