debugg-ai/debugg-ai-mcp

AI-powered browser testing via the Model Context Protocol. Point it at any URL (or localhost) and describe what to test — an AI agent browses your app and returns pass/fail with screenshots.
Setup
**Requires Node.js 20.20.0 or later** (transitive requirement from posthog-node@^5.26.0).
**Testing http://localhost:... URLs requires the caddy binary** — check_app_in_browser,
probe_page, and trigger_crawl tunnel localhost targets through a local Caddy reverse proxy.
This installs automatically: the @radically-straightforward/caddy npm dependency downloads a
pinned Caddy release for your platform during npm install/npx — nothing to install yourself in
the normal case. It is now the **only** binary this package downloads; the tunnel client itself is
pure TypeScript — it replaced the ngrok package, which fetched the ngrok agent.
If that download never ran (npm install --ignore-scripts, an offline/air-gapped install), point CADDY_BIN at
your own install (brew install caddy / apt install caddy / see
caddyserver.com/docs/install) — missing it surfaces as a
clear error on the first localhost-URL call, not a silent hang. Public-URL calls, every
non-browser tool, and test_suite {action:"run"} (which uses its own dedicated tunnel and
bypasses Caddy entirely) don't need it either way.
Get an API key at debugg.ai, then add to your MCP client config:
Or with Docker:
The Dockerfile's npm install step would pick up caddy the same automatic way local installs
do, in principle — but as of this writing the Dockerfile doesn't COPY several directories the
build now needs (handlers, tools, types, config) and still references a tunnels/
directory that no longer exists, so a fresh build likely fails before that matters. That's a
pre-existing gap, unrelated to Caddy. The **currently published** quinnosha/debugg-ai-mcp image
predates the Caddy dependency regardless — localhost-URL calls to
check_app_in_browser/probe_page/trigger_crawl will fail with CaddyBinaryNotFoundError
inside that image until it's rebuilt (Dockerfile fixed) and republished, or CADDY_BIN points at
one baked in separately. Public-URL calls, the non-browser tools, and test_suite {action:"run"}
are unaffected either way.
Tools
The server exposes **8** tools: three **Browser** tools plus one **action-based** tool per managed entity. The headline tools are check_app_in_browser (full AI agent) and probe_page (lightweight no-LLM page probe). The rest — project, environment, test_suite, test_case, executions — each take an action discriminator (e.g. {"action":"list"}) that selects the operation. Destructive delete actions require confirmation (an elicitation prompt where supported, otherwise confirm: true).
Browser
check_app_in_browser
Runs an AI browser agent against your app. The agent navigates, interacts, and reports back with screenshots. Localhost URLs are auto-tunneled through the debugg tunnel server.
| Parameter | Type | Description |
|-----------|------|-------------|
| description | string **required** | What to test (natural language) |
| url | string **required** | Target URL — http://localhost:3000 is auto-tunneled |
| environmentId | string | UUID of a specific environment |
| credentialId | string | UUID of a specific credential |
| credentialRole | string | Pick a credential by role (e.g. admin, guest) |
| username | string | Username for login (ephemeral — not persisted) |
| password | string | Password for login (ephemeral — not persisted) |
| loginCredentials | array | Accounts for logins the agent hits **during** the task — [{username, password, label?}] |
| useEnvironmentCredentials | boolean | Default true. false forbids auto-filling the environment's stored credentials; with no account named it means **do not log in at all** |
| freshSession | boolean | Default false. true forces a real login instead of reusing the warm session held for that account |