bugAgent

Connect bug Agent to any MCP-compatible AI client.

File, classify, and manage bugs, feature requests, and more directly from your AI coding assistant. No context switching, no copy-paste — just describe the issue and bug Agent handles the rest.

External MCP clients are separate from bug Agent 's dashboard AI Assistant. The dashboard assistant is off by default on every plan and requires explicit workspace enablement; its ai_assistant gate does not disable MCP or integrations. MCP authentication, scopes, workspace/project permissions, and tool-specific entitlements still apply.

Getting Started

bug Agent runs the hosted MCP server so AI clients can create, query, and manage bug reports, feature requests, enhancements, and more through the Model Context Protocol. Clients connect directly to the hosted Streamable HTTP endpoint.

Get your API key

Create a Free account; new workspace owners are taken directly to API-key setup. Returning users can generate a key from Settings → Developers → API Keys.

Configure your AI client

Add bug Agent as an MCP server in your client's config (see setup below).

Start filing bugs

Describe a bug in natural language and bug Agent auto-classifies, enriches, and stores it.

# Create a bug report
"File a bug: Login button is unresponsive on iOS Safari.
Steps: tap login, nothing happens. Expected: navigate to
dashboard. Severity: high."

# bugAgent auto-classifies as UI bug, severity high

# File a feature request
"Feature request: Add dark mode toggle to the
settings page. Users have asked for this in surveys."

# Auto-classified as feature-request, severity medium

Setup

Recommended: hosted Streamable HTTP

Connect directly to https://mcp.bugagent.com/mcp. There is nothing to install or keep running locally. Add your workspace API key as a bearer token:

{
  "mcpServers": {
    "bugagent": {
      "type": "http",
      "url": "https://mcp.bugagent.com/mcp",
      "headers": {
        "Authorization": "Bearer ba_live_YOUR_KEY_HERE"
      }
    }
  }
}

💡

Replace ba_live_YOUR_KEY_HERE with your actual API key from Settings → Developers.

Optional stdio bridge

Use the published bridge only when a client requires stdio and cannot connect to a remote HTTP server. Run it on demand with npx -y bugagent-mcp:

{
  "mcpServers": {
    "bugagent": {
      "command": "npx",
      "args": ["-y", "bugagent-mcp"],
      "env": {
        "BUGAGENT_API_KEY": "ba_live_YOUR_KEY_HERE"
      }
    }
  }
}

Connect to the Server

The bug Agent MCP server is live at https://mcp.bugagent.com/mcp over Streamable HTTP transport. Connect from any of the eight clients below — pick the one that fits your workflow.

For a small copy-ready configuration, scoped-key guidance, and safe starter prompts, use the public MCP quickstart.

🔑

Get your API key first. Sign in to Settings → Developers, click Create API Key, select the scopes your client needs, and copy the value (starts with ba_live_). You’ll only see it once, so paste it somewhere safe. MCP clients only list tools granted by those scopes. The connection examples below use this key; prompts that require an interactive OAuth/session or a paid-plan entitlement are identified separately.

Option 1 — MCP Inspector (Web UI, recommended for first-time testing)

The official Anthropic tool. Spins up a local web UI where you can click through every tool, fill in parameters, and see responses. Zero config, no IDE required.

macOS (Terminal)

npx @modelcontextprotocol/inspector

Windows (PowerShell or CMD)

npx @modelcontextprotocol/inspector

In the browser UI that opens:

1. Transport Type: select Streamable HTTP
2. URL: https://mcp.bugagent.com/mcp
3. Connection Type: select Proxy (the default — the Inspector proxies through a local Node process to bypass browser CORS)
4. Open Server Settings → Custom Headers and add:
   • Header Name: X-Api-Key
     • Value: ba_live_YOUR_KEY_HERE (no Bearer prefix)
5. Click Connect. The left panel lists the bug Agent tools allowed by the API key scopes you selected.
6. Click any tool (e.g. list_bug_reports), fill in parameters, click Run Tool. Response shows on the right.

Prerequisites: MCP Inspector v2 requires Node.js 22.19 or later. Install a current Node.js release from nodejs.org if you don’t have it.

If Inspector returns invalid_client, it is attempting a saved OAuth connection instead of API-key authentication. Remove the saved server (or clear its stored OAuth state), add it again, and use the X-Api-Key custom header above. Do not put a ba_live_ key in an OAuth client_id field.

Option 2 — Claude Desktop (Mac + Windows)

If you use the Claude Desktop app, you can add bug Agent as a permanent MCP server. With a workspace API key, Claude receives only the tools allowed by that key’s scopes. Delegated OAuth exposes the complete interactive catalog.

macOS

1. Open Claude Desktop → menu bar Claude → Settings → Developer → Edit Config. This opens ~/Library/Application Support/Claude/claude_desktop_config.json.
2. Add the bug Agent entry under mcpServers:

   {
     "mcpServers": {
       "bugagent": {
         "type": "http",
         "url": "https://mcp.bugagent.com/mcp",
         "headers": {
           "Authorization": "Bearer ba_live_YOUR_KEY_HERE"
         }
       }
     }
   }
   

3. Save the file and fully quit Claude Desktop (Cmd+Q, not just close the window).
4. Relaunch Claude Desktop. The tools hammer icon at the bottom of the chat input should now show bug Agent tools.
5. Try it: type “List my 5 most recent bug reports” — Claude will call list_bug_reports automatically.

Windows

1. Open Claude Desktop → File → Settings → Developer → Edit Config. This opens %APPDATA%\Claude\claude_desktop_config.json (typically C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json).
2. Add the same JSON block shown in the macOS section.
3. Save the file and fully quit Claude Desktop from the system tray (right-click the Claude icon → Quit), then relaunch.
4. The tools hammer icon will show bug Agent tools.

Option 3 — Claude Code (CLI)

If you use Claude Code from your terminal (the CLI version of Claude), register the bug Agent server with one command. Works identically on macOS, Linux, and Windows.

claude mcp add --transport http bugagent https://mcp.bugagent.com/mcp \
  --header "Authorization: Bearer ba_live_YOUR_KEY_HERE"

Then restart your Claude Code session. Verify it’s connected:

claude mcp list

You should see bugagent in the list with a green dot. Start with an API-key-compatible prompt: “List my 5 most recent open bug reports.”

Connected, but some tools are missing?

Check the server’s tool count in /mcp, not just tools already loaded in the conversation. Claude Code can discover tools on demand using tool search. Ask it to search bugAgent for list_test_cases, list_test_suites or get_test_run_plan. See Claude Code’s tool-search documentation.

The catalog is filtered by API-key scopes. Test-case reads need test_cases:read; suite/run reads need test_runs:read. Request only the write scopes you actually need. Compare authenticated tools/list with the same endpoint and key as your client; anonymous discovery or a different key is not a valid comparison. Check for a project-level configuration overriding your user-level connection, then reconnect or restart after credential changes.

If the authenticated server catalog includes a tool but the client still cannot discover it, record the client version, server version, tool names/counts and any schema errors, with credentials and customer data removed. A session started with ENABLE_TOOL_SEARCH=false claude can distinguish deferred discovery from loading problems, but loads all tool definitions and uses more context; use it only as a temporary diagnostic. Do not broaden permissions or split endpoints merely to increase a tool count.

To remove it later:

claude mcp remove bugagent

Option 4 — OpenAI Codex CLI

If you use the OpenAI Codex CLI, export your API key and add bug Agent to ~/.codex/config.toml.

Permanent registration (add to config)

[mcp_servers.bugagent]
url = "https://mcp.bugagent.com/mcp"
bearer_token_env_var = "BUGAGENT_API_KEY"

Set the API key

export BUGAGENT_API_KEY="ba_live_YOUR_KEY_HERE"

Start or restart Codex from that environment. Codex resolves tool calls automatically from your natural-language prompt. Try: “List my open bugs sorted by severity.”

Option 5 — Cursor (Mac + Windows)

Cursor has built-in MCP support. With an appropriately scoped workspace API key, the AI assistant inside Cursor can file bugs, list reports, and run supported automation workflows without leaving your editor. Security, performance, and exploratory scans require delegated OAuth and applicable plan access.

1. Open Cursor → Settings (Cmd+, on Mac / Ctrl+, on Windows) → MCP in the left sidebar.
2. Click + Add new MCP server.
3. Select HTTP transport type.
4. Fill in:
   • Name: bugagent
     • URL: https://mcp.bugagent.com/mcp
     • Header name: Authorization
     • Header value: Bearer ba_live_YOUR_KEY_HERE
5. Click Save. Cursor shows a green indicator when connected.
6. Open Cursor’s chat (Cmd+L / Ctrl+L) and type “Create a bug report titled ‘Login broken’ with severity high.” Cursor will invoke create_bug_report.

Alternative: Cursor also reads ~/.cursor/mcp.json (Mac) or %USERPROFILE%\.cursor\mcp.json (Windows). Add the same JSON format shown in the Claude Desktop section.

Option 6 — VS Code with Continue extension (Mac + Windows)

If you prefer VS Code, the Continue extension supports MCP servers natively.

1. Install the Continue extension from the VS Code marketplace.
2. Open Continue’s config: Command Palette (Cmd+Shift+P / Ctrl+Shift+P) → Continue: Open config.json. The file is at:
   • macOS: ~/.continue/config.json
     • Windows: %USERPROFILE%\.continue\config.json
3. Add an mcpServers entry:

   {
     "mcpServers": [
       {
         "name": "bugagent",
         "type": "streamable-http",
         "url": "https://mcp.bugagent.com/mcp",
         "requestOptions": {
           "headers": {
             "Authorization": "Bearer ba_live_YOUR_KEY_HERE"
           }
         }
       }
     ]
   }
   

4. Save. Continue will auto-reload and show the bug Agent tools in the sidebar.
5. Open the Continue chat panel and try: “List my 5 most recent open bug reports.”

Other VS Code MCP-capable extensions: Cline, Roo Code, and Windsurf (fork) all follow similar JSON config patterns with an mcpServers key and HTTP transport.

Option 7 — OAuth-aware hosts (Claude.ai web shown as the example)

Some MCP hosts authenticate via OAuth 2.0 and ask for a static client_id and client_secret upfront instead of accepting a bearer API key. Generate a connector credential pair from the bug Agent dashboard and paste it into the host’s connector form. The pair identifies the MCP client; after consent, tool execution uses the signed-in user and that user’s active bug Agent workspace. The walkthrough below uses the Claude.ai web app as the most common example.

i

Resource-bound OAuth. The protected resource identifier is https://mcp.bugagent.com/mcp. Standards-aware hosts discover it from /.well-known/oauth-protected-resource/mcp and send it as the RFC 8707 resource parameter. bug Agent issues opaque tokens bound to that resource, OAuth client, signed-in user, and granted scopes; a token cannot be replayed against another service or redeemed by another client.

1. In bug Agent: open Settings → Developers → MCP Connectors. Click Generate connector, give it a name describing the host (e.g. “Claude.ai (work)”), paste the redirect URI your MCP host requires (for the Claude.ai web app that’s https://claude.ai/api/mcp/auth_callback — check your host’s connector docs for others), and choose Confidential for the auth method. Copy the client_id and client_secret shown once on the success screen.
2. In your MCP host’s connector / OAuth settings, paste:
   • Server URL: https://mcp.bugagent.com/mcp
     • Client ID + Client Secret: from step 1
     • Authorization URL: https://mcp.bugagent.com/authorize
     • Token URL: https://mcp.bugagent.com/token
     • Protected resource / audience, when requested: https://mcp.bugagent.com/mcp For Claude.ai specifically: go to claude.ai/customize/connectors and click Add MCP connector.
3. Save. The host redirects you to bug Agent to sign in (Google or email/password — whichever method you use for the dashboard) and approve consent, then completes the OAuth handshake.
4. Manage and revoke generated connectors from the same Settings page. Revoking is immediate — the next request from that connector returns invalid_client.

Note: Claude Code, Cursor, VS Code, and the MCP Inspector don’t need this flow — they handle dynamic client registration (RFC 7591) automatically and authenticate via API key as shown above. The MCP Connectors form is only for hosts that require static OAuth credentials.

OAuth access and refresh values are displayed only to the host. They are opaque, rotated on refresh, and stored by bug Agent only as one-way hashes; the upstream identity refresh credential is encrypted at rest. Never copy an OAuth token into a REST API request or another MCP server.

Option 8 — Direct HTTP with curl (Terminal)

If you want to test the server directly without any client, or integrate it into a script, you can hit the HTTP endpoint with curl. The MCP protocol is JSON-RPC 2.0 over Streamable HTTP.

macOS / Linux

# Set your API key as a variable
export BUGAGENT_API_KEY="ba_live_YOUR_KEY_HERE"

# 1. Initialize the MCP connection
curl -N -s https://mcp.bugagent.com/mcp \
  -H "Authorization: Bearer $BUGAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl-example","version":"1.0.0"}}}'

# 2. List tools visible to this key
curl -N -s https://mcp.bugagent.com/mcp \
  -H "Authorization: Bearer $BUGAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. Call a tool — list 5 reports from a specific project
curl -N -s https://mcp.bugagent.com/mcp \
  -H "Authorization: Bearer $BUGAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc":"2.0",
    "id":3,
    "method":"tools/call",
    "params":{
      "name":"list_bug_reports",
      "arguments":{"project":"bugagent","limit":5}
    }
  }'

Windows (PowerShell)

# Set your API key
$env:BUGAGENT_API_KEY = "ba_live_YOUR_KEY_HERE"

# Use Invoke-RestMethod (PowerShell's curl equivalent)
$headers = @{
  "Authorization" = "Bearer $env:BUGAGENT_API_KEY"
  "Content-Type" = "application/json"
  "Accept" = "application/json, text/event-stream"
}

# 1. Initialize
$body = '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"powershell-example","version":"1.0.0"}}}'
Invoke-RestMethod -Uri "https://mcp.bugagent.com/mcp" \`
  -Method Post -Headers $headers -Body $body

# 2. List tools visible to this key
$body = '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
Invoke-RestMethod -Uri "https://mcp.bugagent.com/mcp" \`
  -Method Post -Headers $headers -Body $body

# 3. Call list_bug_reports for a specific project
$body = @{
  jsonrpc = "2.0"
  id = 3
  method = "tools/call"
  params = @{
    name = "list_bug_reports"
    arguments = @{ project = "bugagent"; limit = 5 }
  }
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Uri "https://mcp.bugagent.com/mcp" \`
  -Method Post -Headers $headers -Body $body

Responses may be JSON or Server-Sent Events. Each SSE chunk is a line prefixed with data: followed by a JSON object. Standards-compliant clients should send Accept: application/json, text/event-stream; bug Agent currently normalizes missing or incomplete Accept values for compatibility.

ℹ️

Troubleshooting 401 Unauthorized: Check that your API key hasn’t been revoked in Settings → Developers. Keys start with ba_live_. If you’re still stuck, regenerate the key and retry.

Access model and least-privilege scopes

The complete OAuth catalog contains 141 tools. A workspace API key sees only tools mapped to one of its selected scopes. Unauthenticated discovery may show tool metadata, but tools/call always requires an API key or OAuth token.

Read bug reports and resolve projects reports:read

Create and update bug reports reports:read, reports:write

Usage monitor usage:read

Check Jira sync state jira:read

Sync or merge Jira reports jira:write

Author web automations automations:write

Run web automations and read runs automations:run

Observe mobile assets and runs mobile:read

Manage mobile assets mobile:read, mobile:write

Run mobile automation mobile:read, mobile:run

Manage the test catalog reports:read, test_cases:read, test_cases:write

External test execution worker test_runs:read, test_runs:write

API keys are bound to the workspace where they are created. Tool inputs may narrow a call to an authorized project, but cannot switch the key to another workspace. Resolve project UUIDs with list_projects and reject ambiguous names.

Tool titles and annotations

Every tool returned by tools/list includes a human-readable title and read/write hints. Missing read hints come from an explicitly reviewed list, not tool-name prefixes or API-key scopes. Explicit annotations, including false, are preserved.

• readOnlyHint: true describes a tool that does not modify its environment.
• readOnlyHint: false with destructiveHint: false describes additive writes, not a read-only operation.
• readOnlyHint: false with destructiveHint: true describes potentially destructive writes. Unclassified tools use these conservative defaults. The destructive hint is meaningful only for writes.

login is not read-only: in stdio mode it saves credentials. analyze_fix_area and check_config_drift are potentially destructive writes because they replace persisted analysis results or configuration baselines.

Annotations do not grant access or replace authentication, workspace/project authorization, API-key scopes, or entitlement checks. Confirmation prompts depend on the client's permission policy and user settings; the hints do not guarantee whether a call will prompt.

For programmatic discovery and auditing, download the generated mcp-tool-index.json. It records all 141 runtime tools, API-key scope or OAuth-only access, entitlement family, input names, output-schema mode, and explicitly declared MCP annotations. A null annotation means it is not declared at the call site; use the connected server's tools/list response for effective annotations after defaults are applied.

!

OAuth-only tools: account, API-key and team administration, Jira connection management, other integrations, premium testing controls, notes, time tracking, and other interactive operations are not unlocked by adding API-key scopes. Jira report check, sync, and merge tools are the narrow exception through jira:read and jira:write.

Try It — Plain-English Prompts

Once connected, you don’t need to know tool names or parameters. Describe what you want in plain English and your AI assistant calls the right bug Agent tool automatically.

Bug-report, scoped test-management, Playwright automation, mobile automation, and usage prompts are available to API keys with the matching scopes. Security, performance, exploratory, account, team, notes, time tracking, and other entries without a named API-key scope require delegated OAuth and any applicable plan entitlement.

Bug Reports

List my 5 most recent bug reports
Show all open critical bugs in the Auth project
Create a bug titled "Login broken on Safari" with severity s2
Update TEST-451 status to in-progress and assign it to me
Add a comment to TEST-451: "root cause confirmed — null check missing in auth middleware"
Show me everything filed this week, grouped by severity

Test Management

Create a test suite called "Smoke Tests" with cases for login, checkout, and account settings
Run the Regression suite and list all failures
Use Hermes to execute the curated "Checkout smoke" suite and report every result to bugAgent
Show failing test cases from the last 7 days
Which test cases have never been run in the past 90 days?
Get a pass-rate trend for this month vs last month

Security & Performance

Run a security scan on https://app.example.com
Get this month's security scan results — show only high and critical findings
Create a performance test for the landing page and check Lighthouse scores
What are the Core Web Vitals for our checkout flow?

Playwright Automation

Create a Playwright script that logs in and verifies the dashboard loads
Run the checkout automation on iPhone 15 Pro on a real device
Optimize the login automation script
Show runs for the checkout automation — any failures?
Schedule the smoke test suite to run every weekday at 6 AM UTC

Exploratory AI

Run an exploratory AI session on https://app.example.com with 5 parallel agents
Get the latest exploration run results — list any bugs that were filed
What testing strategies did the agents use and which found the most issues?

Usage & Stats

Check my plan usage for this month
Show team bug stats for this week broken down by severity and type
List all team members and their roles
How many security scans do I have left this month?

Quick Reference

Setup references for all eight connection options. API-key clients connect to https://mcp.bugagent.com/mcp with the header Authorization: Bearer ba_live_YOUR_KEY_HERE over Streamable HTTP; OAuth-aware hosts use connector credentials generated in the dashboard.

Claude Desktop — macOS ~/Library/Application Support/Claude/claude_desktop_config.json

Claude Desktop — Windows %APPDATA%\Claude\claude_desktop_config.json

Claude Code (CLI) claude mcp add --transport http bugagent https://mcp.bugagent.com/mcp --header "Authorization: Bearer ba_live_..."

Codex CLI ~/.codex/config.toml

Cursor — macOS Settings → MCP UI, or ~/.cursor/mcp.json

Cursor — Windows %USERPROFILE%\.cursor\mcp.json

VS Code + Continue ~/.continue/config.json (macOS) / %USERPROFILE%\.continue\config.json (Windows)

OAuth-aware host Settings → Developers → MCP Connectors — generate the host’s client_id and client_secret

Direct HTTP (curl) curl / Invoke-RestMethod — include Accept: application/json, text/event-stream

Troubleshooting

401 Unauthorized Key is wrong, expired, or revoked. Check Settings → Developers — keys start with ba_live_. Regenerate if needed.

Tools not showing in client API-key clients only list tools allowed by the key’s selected scopes. Check the key in Settings → Developers, then fully quit and relaunch the client after changing its config. In Claude Desktop, Cmd+Q (not just close the window). In Cursor, check Settings → MCP for a green dot.

Field missing in the client Compare the client’s schema with the same endpoint’s raw tools/list. If they differ, refresh or reconnect the tool catalog and start a new chat. If it persists, collect the endpoint, client version, and raw tools/list response; a stale cache is only one possible cause.

Accept header required Send Accept: application/json, text/event-stream for standards-compliant Streamable HTTP. bug Agent currently normalizes missing or incomplete values, but integrations should not rely on that compatibility behavior.

Wrong workspace’s data Each API key is scoped to one workspace. Generate a new key from the workspace you want to query in Settings → Developers.

Tools appear but calls fail silently Inspect the response for isError: true and returned content. A visible tool can still be denied by plan, role, feature entitlement, project membership, ownership, or invalid input. Check server health only after reading the tool error.

MCP Inspector CORS error Select Proxy (not Direct) for Connection Type in the Inspector UI. The Inspector proxies through a local Node process to bypass browser CORS restrictions.

MCP Inspector v2 exits with code 5 Inspector v2 returns a nonzero exit code when a tool response has isError: true. Read the response message for a plan, permission, input, or runtime error; Inspector v1 could return exit code 0 for the same failed tool response.

Codex CLI — tools not recognized Verify ~/.codex/config.toml uses [mcp_servers.bugagent], set bearer_token_env_var = "BUGAGENT_API_KEY", and export that variable before starting Codex. Check codex --version if tools still do not appear.

MCP Features

Conversational Sessions remain a workspace-gated pilot. Saving a session-generated script requires its owner's explicit Workbench approval through the session-only save-script endpoint. There is no MCP approval tool: asking an agent to draft a script does not create or schedule an automation.

The complete interactive/OAuth catalog contains 141 tools. Workspace API keys discover only the least-privilege subset allowed by their selected scopes; account, API-key administration, team administration, premium testing, notes, and time-tracking tools are interactive-session only unless an entry explicitly names an API-key scope.

🐛

Bug Report Management

Resumable Google Sheets screenshot imports use the separate REST POST /api/reports/import-attachment endpoint with reports:write, and GET status with reports:read. No screenshot-import MCP tool is added. This JPEG/PNG-only API verifies private storage and the exact mapped Jira issue before reporting completion; legacy report upload remains session-only.

• create_bug_report — File a new report with auto-classification across 19 types — bugs, feature requests, enhancements, technical debt, and more (title: 3-500 chars). Optional attachments array accepts base64-encoded files up to 400 MB each: any image, video, audio, PDF, or text/JSON. Set format_description: true to auto-reformat the description into a structured template using AI. Pass time_spent_seconds to track QA effort. Pass priority (urgent / high / normal / low) to set the fix urgency independently of severity. Pass is_epic: true to create an Epic, or parent_epic_id (UUID/short ID) to create a child in the same authorized project. The response includes hierarchy fields plus project_id, project, short_id, legacy_short_id, and project_short_id.
• list_bug_reports — List and filter reports (max 100 per page). Project filters are applied server-side before pagination. Filter by project (UUID, slug, exact name, or ticket prefix), project_id, project_slug, project_prefix, workspace (UUID, exact name, or workspace ticket prefix), workspace_id / team_id, is_epic, type, severity, status, resolution, root_cause, or reporter_user_id. The search filter searches report text; digits-only input such as 366 is an exact lookup against both legacy and project ticket numbers, so unrelated text containing those digits is excluded. Each result includes tenant-scoped people/project identifiers plus is_epic, parent_epic_id, parent_epic, and bounded epic_progress. Report-read tools do not expose member email addresses.
• pick_next_bug — Returns the next bug(s) the agent loop should work on, in priority order (S1 → S2 → S3, oldest first within each bucket). Automatically scoped to your workspace — returns tickets across all projects in your team with status new, awaiting-triage, or confirmed and severity S1-S3. Read-only — does not atomically claim tickets. Optional severity (single tier), limit (1-50, default 1). Returns an object with count and bugs; each bug is a reduced queue row rather than the full list_bug_reports shape. Pair with claim_bug for the read-then-claim pattern.
• claim_bug — Atomically transition a bug from status new, awaiting-triage, or confirmed to status='in-progress', set assigned_to to the calling user, and stamp claimed_at=NOW(). Race-free across concurrent callers via Postgres' UPDATE-WHERE-RETURNING pattern — if two agents call claim_bug on the same id in close succession, exactly one gets claimed:true with the bug body and the other gets claimed:false with a reason string. Successful responses include reporter_user_id, reporter_name, assigned_to, and assignee_name. A pg_cron reaper releases stale claims (status= in-progress + claimed_at > 30 minutes old) back to new automatically, so a crashed agent's tickets re-enter the queue without manual intervention. Inputs: id (UUID or short ID).
• get_bug_report — Get full details of a report by UUID or workspace/project short ID. Returns the standard people/project/quality fields plus is_epic, parent identity, aggregate progress, and a bounded first child page for Epics.
• Native report tags: create_bug_report and update_bug_report accept tags as a string array, for example {"tags":["login","regression"]}. At most 20 raw elements are accepted before deduplication. Strings are trimmed, must be nonempty and at most 50 Unicode code points, and cannot contain ASCII controls (U+0000 through U+001F or U+007F). Exact duplicates are removed after trimming; casing is preserved and Login differs from login. On update, the array replaces all tags, [] clears them, and omission preserves them. On create, omission means no tags. null and invalid elements are rejected. Create, get, list and update results expose native tags.
• Tag filtering: call list_bug_reports with {"project":"bugagent","tags":["login","regression"]} to match ALL requested tags, case-sensitively, before pagination. The same tag limits apply; omission or [] applies no tag filter. Existing reports:read / reports:write scopes and workspace/project authorization are unchanged. This adds no visual tag UI or automatic Jira-label import, synchronization or backfill.
• get_epic — Read one Epic directly with required id (UUID or workspace/project short ID). Returns the Epic record only, without implicitly loading child reports. Requires access to its workspace and project; API-key callers require reports:read. Use list_epic_children separately to read children.
• list_epic_children — Paginate an Epic's child reports with id, limit (1–100), and offset. Returns children, total, has_more, and SQL-aggregated epic_progress without loading every child report.
• update_bug_report — Update standard report fields plus is_epic and parent_epic_id. Pass parent_epic_id: null to detach; reparent/detach is atomic and requires same-workspace, same-project authorization. Promoting to an Epic detaches an existing parent, while an Epic with children cannot be demoted. Existing status/resolution/root-cause and assignment notification rules still apply. A status change on a Jira-linked report is mirrored to the Jira issue via its workflow transitions when exactly one legal transition matches the mapped status; otherwise the issue is left untouched.
• add_comment — Add a comment to a bug report (UUID or short ID, body 1-10000 chars). If the report is synced to Jira, the comment is automatically pushed to the linked Jira issue. Private attachment markdown such as ![proof](/api/attachments/ATTACHMENT_UUID) becomes an absolute authenticated bugAgent smart link in Jira. Viewers must sign in to bugAgent with access to the report’s workspace and project; native inline Jira previews are not guaranteed.
• list_comments — List a report's stored comment thread, oldest first — each comment with author name, parentId (threaded replies), createdAt, and updatedAt. Comments are not part of get_bug_report, so this is how you read a ticket's discussion. Accepts UUID or short ID. This read does not refresh Jira. Scheduled integrations that need fresh Jira comments can first call POST /api/jira/comments-refresh with an authorized manager-owned API key. Use comment IDs and content revisions to distinguish new comments from edits, and do not claim a complete activity report if refresh fails.
• link_bug_reports — Create a directional semantic link between two reports in the same authorized project. For parent-of, the from-report must be an Epic and the to-report a standard child. Prefer parent_epic_id on create/update for Epic assignment.
• unlink_bug_reports — Remove a previously-created bug-report link by its UUID (link_id, returned by link_bug_reports or list_bug_report_links).
• list_bug_report_links — List every user-curated link touching a bug report. Returns each link as it reads from the supplied report's perspective — e.g. a stored duplicate-of row where this report is the target renders as duplicated-by; parent-of where this report is the target renders as subtask-of; depends-on where this report is the target renders as blocks; testing-blocked-by where this report is the target renders as blocks-testing. related-to is symmetric. Complements the auto-detected similar_reports field returned by get_bug_report.
• classify_bug — Classify a description into one of 19 report types (bugs, features, enhancements, etc.) with confidence score
• flush_reports — Bulk delete old reports (admin only)

📊

Usage & Analytics

• get_usage — Check usage against plan limits. API-key callers require usage:read.
• get_stats — Daily counts, type/severity/status breakdowns

📁

Project Management

• list_projects — List accessible projects with id, name, slug, ticket_prefix, description, and default status. Use those values with bug-report and test-catalog tools to target the correct project.
• create_project — Create a new project (auto-becomes default if first)
• delete_project — Permanently delete a project and all associated data (bug reports, automations, test cases, mobile apps, schedules, geo snaps, notes, time entries). Only owner/manager. Cannot delete last project. Storage is freed automatically
• export_okf_bundle — Export a project’s QA knowledge — bug reports, test cases, automations, and performance, security, and exploratory tests — as an OKF/OQA markdown bundle (the Open Query Agent format used by oqa.ai). Defaults to the active project; pass the optional project (slug or name) to export a different one. Returns the list of files in the bundle plus the bundle itself as a base64-encoded zip

🔐

Authentication & Account

• register_account — Create a new account (password: 8-128 chars, rate limited: 5/15min)
• login — Sign in and receive access tokens (rate limited: 5/15min)
• update_profile — Update display name
• change_password — Change account password
• get_settings — Read profile and notification preferences.
• update_settings — Update supported profile and notification preferences. OAuth-only mutation.

🔑

API Key Management

• generate_api_key — Create a named API key
• list_api_keys — List active keys (prefix only)
• regenerate_api_key — Revoke and replace a key
• delete_api_key — Permanently revoke a key

👥

Team Management

• list_workspaces — List the workspaces you belong to, your role in each, and which one the session uses by default. Multi-workspace hosts can pin a request with the X-BugAgent-Workspace header (active members only)
• list_team_members — List all members of your workspace with roles, status, and booster flags
• invite_team_member — Invite a user by email (managers can invite contributors and managers; only owners can invite admins). 5-day expiry link

🎯

Integrations

Jira Cloud report sync is included on Free and Enterprise. A workspace manager must first connect Jira in the dashboard. Workspace API keys can then use jira:read for comparison and jira:write for sync/merge; Atlassian plan and API limits still apply.

• sync_to_jira — Push a report to Jira using the team's shared connection. Routes to the Jira project mapped to the report's bugAgent project (workspace default as fallback), using its field map: v2 separates priority and custom severity, while unversioned maps retain legacy severity-to-priority translation. Optional projectKey may select only that configured mapping or workspace default; arbitrary Jira projects are rejected. You usually don't need this: when the project's sync mode is auto_new or auto_all, reports you create are pushed automatically — call it for a manual push in manual mode.
• check_jira_sync — Read-only comparison of title and mapped status, priority, and severity for an authorized linked report. Uses the report's saved project and Jira connection. Version 2 maps Jira Priority separately from a supported custom Severity field; unversioned mappings retain legacy priority-to-severity behavior. This tool does not compare comments, attachments, type, or every Jira field.
• merge_jira_sync — Merge those mapped fields using prefer: jira to pull Jira values or prefer: bugagent to push local values. Status pushes use legal Jira workflow transitions. Unmapped outbound conflicts, failed remote writes, and concurrent local changes return errors rather than claiming everything is in sync. Comments and attachments remain separate dashboard sync workflows. Cross-system writes are not atomic.
• push_to_claude — Generate (or regenerate) the Developer Notes for a bug report — root cause, suggested fix, verification steps, and risk assessment. Accepts UUID or short ID (WRKID-545). Uses platform keys — no per-team Claude connection required. Runs an adaptive chain: three steps on s3 / medium or s4 / low bugs (Sonnet draft → OpenAI gpt-5 critique → Sonnet synthesis), five steps on the top-two severity buckets — s1 / critical or s2 / high — (draft → critique → Sonnet rebuttal → Claude Opus adjudicator that reads the full transcript and writes the final notes with independent judgment). Response exposes every round: analysis, draft, critique, rebuttal, challenger_model, adjudicator_model, and a debated flag. Any step failing falls through to the next-best answer. Auto-fires on bug creation; usually only called for manual regenerate.
• analyze_fix_area — Generate (or regenerate) the "Likely Fix Area" sub-block of Developer Notes — a narrow Sonnet output that names where in the codebase the fix most likely belongs. Accepts UUID or short ID. Uses the platform Anthropic key. When the team has a github_connections row and the project has a github_repo mapped, output is grounded in real file snippets from the connected repo; otherwise falls back to general guidance with a nudge to connect a repo. Returns likely_fix_area text, generated_at, repo_used, and a grounded flag. Auto-fires on bug creation — agents typically only need to call this for manual regenerate.
• upgrade_plan — Get the sales-assisted Enterprise enrollment link

⚡

Performance Testing

• create_performance_test — Create a performance test config with URL, device, virtual users, duration, score threshold, and auto-bug creation toggle. Enterprise only
• run_performance_test — Trigger a page audit and load test for a web performance test. Returns a run ID to poll for results. Mobile app profiling runs are triggered from the dashboard
• get_performance_results — Get full results including Lighthouse scores (Performance, Accessibility, Best Practices, SEO), Core Web Vitals (LCP, FID, CLS, FCP, TTFB, INP, TBT, SI), and load test metrics (VUs, requests, RPS, p50/p90/p95/p99 latencies)
• list_performance_tests — List all performance test configurations for the current team
• get_performance_usage — Check monthly performance test usage. Performance testing is Enterprise-only. Free=0, Enterprise=unlimited

Example Workflow

1. get_performance_usage → check remaining quota
2. create_performance_test → configure a test for your URL
3. run_performance_test → trigger the audit + load test
4. get_performance_results → review scores and vitals

🛡

Security Scanning

• create_security_scan — Create a security scan configuration. Web scans use Quick Scanner + Nuclei (4,000+ templates) with three depth levels and optional authenticated scanning. Mobile scans use MobSF for APK/IPA binary analysis. Configurable auto-bug creation with severity thresholds. Enterprise only
• run_security_scan — Trigger a vulnerability scan. Web scans require DNS domain verification. Mobile scans require an uploaded app. Returns a run ID to poll for results
• get_security_results — Get full results including security score (0-100), findings categorized by severity (Critical, High, Medium, Low, Info) with CWE references, OWASP mappings, evidence, and remediation guidance
• list_security_scans — List all security scan configurations for the current team with last score and auth/depth badges
• get_security_usage — Check monthly security scan usage. Security scanning is Enterprise-only. Enterprise=unlimited
• list_security_schedules — List all scheduled security scans for the team with cron, timezone, enabled state, next run, and notification settings. Joins with the parent scan config (name, scan_type, target_url)
• create_security_schedule — Create a recurring schedule for a security scan. Requires scan_id and cron_expression. One schedule per scan config. Optional timezone, notify_on_fail (none/email/slack/both), notify_email, slack_channel_id. Every run counts against your monthly cap; admin users bypass the cap. Scan depth is always read from the scan config at run time
• delete_security_schedule — Delete a scheduled security scan. Does not affect the parent scan config or completed runs

Example Workflow

1. get_security_usage → check remaining quota
2. create_security_scan → configure a scan for your URL or repo
3. run_security_scan → trigger a one-off vulnerability scan
4. create_security_schedule → automate recurring runs (e.g. weekly SAST on main branch)
5. get_security_results → review findings and remediation

📖

Code Review

• list_code_reviews — List recent AI code reviews for the team. Returns quality scores, severity counts, PR info, and timestamps. Enterprise only
• get_code_review — Get a code review with all findings. Each finding includes severity, category (bug/security/performance/style/logic/maintainability), title, description, code suggestion, file path, and line numbers
• get_code_review_usage — Check code review usage. AI code review is Enterprise-only; unlimited on Enterprise
• get_code_review_analytics — Get review analytics: trends, finding categories/sources, severity breakdown, velocity metrics, top repos/authors. Supports 7/30/90-day lookback

Example Workflow

1. get_code_review_usage → check remaining reviews
2. Review a PR in the dashboard at /dashboard/code-review
3. list_code_reviews → see recent reviews
4. get_code_review → get findings and suggestions

🔍

Exploratory AI

Multi-agent autonomous website bug finder with up to 10 parallel agents, each using a different testing strategy.

• list_explorations — List Exploratory AI configs for the team
• create_exploration — Create a new exploration. Accepts agent_count (1–10, max 10) to run multiple parallel agents with unique strategies: happy_path, edge_case, security, accessibility, error_path, performance, mobile, data_integrity, navigation, custom. This tool cannot configure credentials or auth mode. Configure and launch Test login flow only explicitly through the dashboard or REST, then use get_exploration and get_exploration_run to inspect configuration and results. Never infer the mode from instructions or put credentials in MCP arguments. Default credential-based exploration still requires a reusable session.
• get_exploration — Get exploration config with agent settings, safe authentication metadata, and recent runs. Passwords and ciphertext are never returned.
• get_exploration_run — Get run results with per-agent progress, phase data, findings with agent attribution (agent_index, agent_strategy), and linked bugs
• get_exploration_usage — Check monthly usage. Exploratory AI is Enterprise-only; Enterprise: unlimited (10 agents)

Example Workflow

1. create_exploration with agent_count: 5 → configure 5 parallel agents
2. Trigger a run from the dashboard or via POST /api/explorations/run
3. get_exploration_run → poll for per-agent progress and findings
4. View deduplicated findings with agent attribution in the dashboard

📝

Notes

• list_notes — List notes with optional keyword, project, visibility, folder, tag, archive, wiki, date-range, and sort filters. Returns notes the user owns or notes shared with them.
• create_note — Create a note in one of 5 formats: markdown, plain, bugtemplate, checklist, outline. Set visibility to private or shared. Auto-title from first 30 characters if no title provided. Optional attachments array accepts base64-encoded files up to 400 MB each: any image, video, audio, PDF, or text/JSON. Pass time_spent_seconds to track QA effort.
• get_note — Get full note details including content and attachments. Requires id.
• update_note — Update title, content, format, visibility, project, or time_spent_seconds. Pass an attachments array to append new files (max 400 MB each) to the note’s existing attachments without replacing them. Only the author can update. Requires id.
• delete_note — Permanently delete a note and its attachments. Only the author can delete. Requires id.
• list_note_folders — List note/wiki folders, optionally scoped to a project.
• create_note_folder — Create a project-scoped note/wiki folder with optional parent, visibility, favorite, and teammate access settings.

Example Workflow

1. create_note → start a testing session note
2. update_note → append observations as you test
3. list_notes → search past notes by keyword or project
4. get_note → retrieve full note with attachments

🤖

Automation

• create_automation — Create a new automation with a custom Playwright script (no FAB recording required). Requires name. Optional: target_url (auto-derived from the first page.goto(...) URL in the script if omitted), script (Node.js/JavaScript/TypeScript or Python — language is auto-detected; defaults to a placeholder), status (draft or active, default: draft), project_id. Returns the automation id. Tip — Duplicate an automation: use get_automation to fetch the original script, then call create_automation with name set to "[Copy] Original Name" and pass the original script, target_url, and project_id. The duplicate starts in draft status with no version history.
• list_automations — List Playwright automation scripts. Filter by project_id or status (draft, active, paused). Returns array of automations with name, target_url, last_run_status, and run_count.
• get_automation — Get full automation details including Playwright script and recent runs. Requires id. Returns the automation with the live script, a script_versions stack (oldest-first, up to 100 prior entries, each { script, source, timestamp }), and a recent_runs array where each run carries the script_version_label / script_version_source that executed. Call this before run_automation if you need to pick a specific historical version.
• run_automation — Trigger an immediate run of a Playwright test. Requires automation_id. Self-healing locators (automatic): when a locator action times out, the runner asks Claude for a working selector and retries the step once — assertions are never healed, so real regressions still fail — and each heal is logged in the run stdout. Emulation mode (default): optional device for an emulated device profile (e.g. desktop, iphone-15). Real mode: set browserstack: true with bs_browser (chrome, firefox, safari, edge), bs_os (Windows, OS X), and bs_os_version to run on a real desktop browser. Real mobile: set bs_os: "android" (devices: "Samsung Galaxy S25 Ultra", "Google Pixel 10", "OnePlus 13R") or bs_os: "ios" (devices: "iPhone 17 Pro Max", "iPhone 16 Pro Max", "iPhone 15 Pro Max") and pass the device name in bs_os_version. Both modes run in the background; Real describes the execution environment, not a visible interactive session. Node.js scripts route through browserstack-node-sdk (covers desktop + Android + iPhone). Python scripts route through browserstack-sdk (pytest-playwright) and cover desktop only — real mobile via Python isn't supported because pytest-playwright's browser_type.connect() can't drive BrowserStack's real-mobile endpoints. Video and network logs captured automatically; console logs desktop-only. Version replay: inspect script_versions with get_automation, then pass the preferred durable version_label (for example "v103"). Legacy version_index remains supported but must not be combined with version_label. Default: when both selectors are omitted, the current saved script runs. Pruned labels and invalid indices are rejected instead of silently running current. The run record stores the exact snapshot that ran, and any bug report auto-created from a failed run deep-links back to that version in the editor.
• list_automation_runs — List recent runs for an automation. Requires automation_id. Returns runs with status, duration_ms, and error_message.
• list_schedules — List all scheduled web automation runs with nullable cron_expression, nullable run_at, once_status, timezone, device, and notification settings. Recurring rows retain null run_at and once_status; one-time rows have null cron. One-time states: pending, claimed, missed, dispatched, failed, uncertain. These are dispatch states, not test outcomes; inspect list_automation_runs for results.
• Recurring web schedules: create_schedule validates five numeric cron fields and the timezone, and returns a future UTC next_run_at. Monthly and annual recurrences are supported. For example, 30 12 23 9 * in America/Toronto means September 23 at 12:30 every year, not a one-time run. Invalid or impossible timing is rejected before creation. When both day-of-month and day-of-week are restricted, both must match. Nonexistent daylight-saving times are skipped; repeated wall-clock times can occur twice. Dispatch occurs on the scheduler's next poll, not necessarily at the exact minute. Existing recurring behavior is unchanged.
• One-time web schedules: call create_schedule with { "automation_id": "AUTOMATION_UUID", "run_at": "2030-12-15T09:30:00-05:00", "timezone": "America/Toronto" }, choosing a future date and omitting cron_expression. Supply exactly one timing field. run_at requires an offset-qualified ISO 8601 future timestamp (explicit offset or Z); the IANA timezone is for display. An enabled pending schedule executes on the first cron poll after due; more than one hour late is marked missed. It is atomically claimed and disabled before dispatch, and cannot be re-enabled once consumed. Definitive dispatch failures are failed; ambiguous dispatch is uncertain and is never automatically retried. Check runs before scheduling another attempt. dispatched does not mean completed or passed. Creation is API/MCP-only, not a new dashboard creation mode.
• Web schedule timezones are IANA identifiers such as America/Argentina/Buenos_Aires. The dashboard picker includes all server-supported regions and cities and defaults to your profile timezone; the MCP timezone default remains UTC.
• create_schedule — Create a scheduled web automation run. Requires automation_id and exactly one of cron_expression or run_at. Supports optional device, timezone, failure notification, email, and Slack channel settings. Connect Slack through the dashboard first and choose a channel the bot belongs to; webhook installation alone is insufficient. See Slack setup and channel discovery.
• One-time rollout and recovery: apply database migration 374_one_time_web_schedules.sql before deploying the matching API/MCP and scheduler code. claimed can persist after a worker crash: inspect run history before creating a replacement for either claimed or uncertain dispatch. A timestamp more than one hour late is never automatically executed.
• Draft web automations: activate the automation before creating a schedule, re-enabling a schedule, or changing its cron expression or timezone. create_schedule verifies workspace and project access before rejecting Draft status. Existing schedules skip cycles while the automation is Draft; pausing, deleting, pinning, and notification-only changes remain available. There is no web update_schedule MCP tool; use the dashboard for those updates.
• delete_schedule — Delete a scheduled web automation run
• list_mobile_schedules — List all scheduled mobile automation runs with devices, cron, timezone, and notifications
• create_mobile_schedule — Create a scheduled mobile automation run on real devices. Requires automation_id and cron_expression; devices is optional.
• delete_mobile_schedule — Delete a scheduled mobile automation run
• optimize_automation_script — Send a Playwright script to Sonnet 4 for AI-powered optimization. Applies a 12-point checklist that fixes selectors, wait strategies, assertions, error handling, auth patterns, mobile compatibility, and strict mode. Requires automation_id. The current script version is saved before optimization. Returns the optimized script and a changes summary.
• undo_automation_script — Revert an automation script to its previous version. Up to 100 previous versions are retained. Requires automation_id. Returns the restored script and the number of versions remaining.

Example Workflow

1. create_automation → create a test with a custom script
2. list_automations → browse available tests
3. get_automation → inspect the Playwright script
4. run_automation → trigger the test
5. list_automation_runs → check results and duration

⏱️

Time Tracking

• list_time_entries — List time entries for the team. Filter by period (today, week, month, all), project_id, category, and sort (newest, oldest, most_time, least_time). Enterprise plan only.
• create_time_entry — Log time spent on QA tasks. Requires description, category, and duration_minutes. Optionally set project_id and entry_date (defaults to today). Enterprise plan only.
• update_time_entry — Update an existing time entry. Requires id. Can update description, category, duration_minutes, project_id, or entry_date. Enterprise plan only.
• delete_time_entry — Permanently delete a time entry. Requires id. Enterprise plan only.

Example Workflow

1. create_time_entry → log 45 minutes of regression testing
2. list_time_entries → view this week's time entries
3. update_time_entry → adjust duration or category
4. delete_time_entry → remove an incorrect entry

☑️

Test Cases

Test management with hierarchical folders, nested suites (up to 3 levels deep with sub-suite auto-expansion on runs), drag-drop reorder, and an analytics Reports tab with KPI trends, failure analysis, suite health, coverage, and tester productivity. All tools call Supabase directly — no HTTP roundtrip, same latency as the dashboard.

Free limits: 10 stored test cases, 1 suite, 3 folders, 128 KB of structured content per case, 2 active workspace API keys, and 10 total test runs per UTC calendar month. Up to 3 of those runs may use Hermes or another external agent, with 1 active external run and at most 10 cases in each external plan. Free API-key MCP traffic is limited to 30 requests per key and 60 per workspace per minute. Enterprise test case storage and runs are unlimited, subject to general platform protections.

AI test-case generation, AI tag suggestions, Figma import, and test-case file attachments require Enterprise. The 128 KB Free structured-content bound is separate from Enterprise file attachments. Free can store URL references. Core MCP test-case tools remain available on Free within the limits above.

Hands-free execution: the run review page is a carousel with one case visible at a time, keyboard shortcuts (P Pass · F Fail · B Block · S Skip), and voice control. Click the mic, then say "Pass", "Fail", "Block", "Skip", "Next", "Previous", "Add notes" (transcribes into the notes field), "Save notes", or "Voice off". Auto-advances to the next untested case on success results; stays put on Fail so testers can dictate details and spawn a bug. Works in Chrome, Edge, and Safari.

Cases & Folders

• list_test_cases — List accessible test cases with an optional project selector plus search, priority, type, status, and sort filters. Add folder_id (null for unfiled) or suite_id for direct membership, without descendants. API-key callers require test_cases:read. limit defaults to 50 (1-200); offset defaults to 0 (0-1000000). The unchanged cases array is accompanied by total / total_count for all authorized matches, limit, offset, has_more, and nullable next_offset. Previously total incorrectly meant page length. Follow next_offset until null; do not infer completion from page length. A continuation beyond offset 1000000 fails explicitly; narrow the filters instead of receiving an unusable cursor or false completion. Pages exceeding 1 MiB of case data fail explicitly: retry with a smaller limit, rather than accepting omitted records. Stable ID tie-breaking is used, but concurrent edits can shift offset pages.
• Pagination example: call list_test_cases with {"project":"test-bed","limit":50,"offset":0}. For 55 matches the response has total:55, has_more:true, next_offset:50. Repeat with offset:50 for the remaining five and has_more:false, next_offset:null.
• create_test_case — Create a test case in the required project selector (UUID, slug, exact name, or ticket prefix; call list_projects first). Two template variants: steps (default) — per-step { action, expected } grid via the steps array; text — single free-form description via text_content. Both fields can be sent in the same call. Optional urls array (max 10 http/https URLs) attaches reference links and is available on Free. File attachments require Enterprise and a dashboard session. API-key callers require test_cases:write.
• Pagination recovery: requesting a case offset past the available results returns an explicit error; restart at offset 0. This can also happen when cases are removed between requests. Follow the returned continuation rather than guessing the next offset.
• Case identifiers: list_test_cases, get_test_case, create_test_case, and update_test_case return the UUID id, immutable short_id (for example TEST-BA-CASE-123), and numeric case_number, including compact update/no-op responses. Legacy projectless cases use TEST-CASE-123. Missing identifiers are returned as null; use the UUID as the fallback. The database assigns identifiers; callers cannot change them or choose them during creation. A prefix rename does not rewrite existing IDs.
• Single-case lookup: get_test_case and update_test_case accept a UUID or full short ID in id; link_test_case_to_bug and list_test_case_links accept either in case_id. Surrounding whitespace, letter case and numeric padding are normalized before exact lookup in the active workspace. Authorization uses the stored workspace and project, not the ID prefix. Bare numbers, partial IDs and wildcard searches are not accepted. Bulk case arrays, execution-result case_id, bug IDs, folder IDs and suite IDs remain UUID-only. Link records retain the UUID case_id.
• Numbering gaps: case numbers need not be contiguous. Editing a URL or incrementing a number can lead to a missing or inaccessible case; it is not a guaranteed next-case action. Discover cases with the list tool and follow its pagination.
• Workspace scope: the same short ID can exist in different workspaces. MCP resolves it only in the active workspace; switch workspace context before using another workspace's short ID. When sharing a dashboard short-ID URL, preserve ?team=<case.team_id>, for example /dashboard/test-cases/TEST-BA-CASE-123?team=<team-uuid>. UUID permalinks retain the existing authorized cross-workspace behavior. MCP does not construct a permalink.
• get_test_case — Get the authorized case record, including steps and identifiers. Does not load change history or execution history. Example: {"id":"TEST-BA-CASE-123"}.
• Execution estimates: get_test_case returns estimated_time_seconds and the compatibility alias estimated_time, both in seconds. A stored 0 stays 0; an unknown or missing estimate is null. The canonical field wins when both names are present, including an explicit null; legacy-only estimated_time values are treated as seconds without conversion. list_test_cases uses estimated_time_seconds. The create_test_case input remains estimated_time, also in seconds; REST requests and responses use estimated_time_seconds.
• list_test_case_folders — List accessible folders. Capped at 500; accepts a flexible project selector and parent_folder_id filter (use "root" for top-level only). API-key callers require test_cases:read.
• get_test_case_folder — Read one test-case folder directly with required id (UUID). Returns the folder record only, without implicitly loading descendant folders or test cases. Requires access to its workspace and project; API-key callers require test_cases:read.
• Test-case type values for list_test_cases, create_test_case, and bulk_update_test_cases: functional (creation default), regression, smoke, integration, performance, security, usability, exploratory. Invalid types are rejected before writing. Use integration for end-to-end flows; e2e, accessibility, and other are not accepted test-case types. Automation script types are a separate contract.
• create_test_case_folder — Create a folder in the required project returned by list_projects (nests up to 3 levels via parent_folder_id). Requires contributor-or-higher workspace access and access to the project. API-key callers also require test_cases:write.
• update_test_case_folder — Update by folder UUID: id, optional name (trimmed, 1-120 characters), nullable description (max 50000 characters), nullable parent_folder_id, and nullable card_color. A parent UUID moves the folder and its subtree within the same workspace and project; null moves it to root. Colour accepts the lowercase palette #1e293b, #7c2d12, #713f12, #14532d, #1e3a5f, #312e81, #581c87, #831843, #4a044e, #fef08a, #fca5a5, #93c5fd; null clears it. Omitted fields are preserved. At least one update field is required. Unknown, misspelled or invalid fields reject the entire request without saving any changes. Self/descendant cycles, names matching a sibling, direct parent, or direct child (ignoring case and surrounding spaces), and subtree depths above 3 (root depth 0) are rejected. Descendant depths update atomically; case IDs and membership are unchanged. Conflicting concurrent changes may fail; re-read the folder before retrying. Requires active contributor-or-higher project access and test_cases:write for API keys. Example: {"id":"folder-uuid","card_color":"#93c5fd"}. Returns the updated id, team_id, project_id, name, description, card_color, parent_folder_id, depth and updated_at. Folder get/list reads also include card_color.
• update_test_case — Patch an existing case by UUID or full short ID in id, with at least one field: name (or alias title), description, preconditions, steps, template_type, text_content, priority, type, status, or folder_id. Omitted fields are preserved; steps replaces the complete array ([] clears). Explicit null clears description, preconditions, text_content, or folder placement; empty text_content also clears. If both name and title are sent, they must match. Priority and type use the creation enums; status is active, draft, or deprecated. A type change aligns type_tags with the new type, matching the PATCH API. No workspace/project moves or file metadata writes. Folders must share the exact workspace and project. Requires test_cases:write. Returns the case summary, id, short_id, case_number, and changed; unchanged values produce changed: false. A confirmed update with an unconfirmed history entry returns warnings; do not repeat the update to repair history. On a concurrent-change error, read the case again before retrying. Suite membership is separate: use the bulk tool below, not suite_id on this tool. No delete tool is exposed.
• bulk_update_test_cases — Apply one action to 1–500 case UUIDs; pass one ID for a single case. set_folder takes params.folder_id (UUID to move, explicit null to unfile). add_to_suite and remove_from_suite take params.suite_id; adding never removes other memberships or moves the folder. Also supports set_priority, set_status, set_type, add_tags, remove_tags, pin, and unpin. API keys require test_cases:write. Returns applied, skipped, and errors; organization actions count confirmed changed rows, deduplicate IDs, and skip existing memberships.
• Placement at creation: create_test_case accepts optional folder_id and suite_id. Discover targets with list_test_case_folders and list_test_suites (suite discovery requires test_runs:read for API keys). Folders are a single catalog location; suites are many-to-many test-plan memberships. Targets must belong to the same authorized workspace and exact project, including legacy unscoped cases. Inaccessible case IDs are skipped without details; mismatched targets are rejected. Invalid creation targets fail before creating a case.
• Partial creation: case creation and suite attachment are separate writes. If attachment fails, the response returns the created case ID, suite_id: null, and a warnings array. Do not repeat create_test_case; retry bulk_update_test_cases with add_to_suite for that returned ID.
• link_test_case_to_bug — Establish traceability between a test case and a bug report UUID (verified_by, covers, or relates). Both records must belong to the active workspace and projects accessible to the caller.
• list_test_case_links — List all traceability links for a test case.
• list_test_case_review_candidates — Dead-test flags: never_run (90+ days since creation), always_passes (5+ consecutive passes in 90d), always_skipped (3+ consecutive skips).
• mark_test_case_review_flags — Persist current archive-candidate flags onto test_cases.review_flag. Runs automatically every Monday 09:00 UTC via pg_cron.

Imports

• Figma import (Enterprise) (dashboard session only): upload a zip export of Figma frames (up to 100 MiB), Claude analyzes each screen and drafts test cases into a folder you pick or create. Before decoding, the archive is limited to 1,000 entries, 20 MiB expanded (decoded) per entry, and 100 MiB aggregate expanded data, including ignored files and directories in the budgets. Decoded frame buffers must match their declared sizes. Malformed archives, size mismatches, and exceeded limits fail the job before AI analysis; the original upload is retained on failure for retry, subject to storage cleanup policy. Valid archives enter a multi-pass pipeline (classify → per-screen cases → flow-level cases across shared-prefix screens → self-critique) with prompt caching, 429 retry, and per-frame AI error isolation. Cases land as status=active, tagged ai_generated=true, with source='figma' and source_frame_name preserving a link to the original frame. Uses the platform Anthropic key — no per-team Claude connection required.

Suites & Runs

• list_test_suites — List up to 50 accessible test suites with an optional flexible project filter. Each suite includes an exact integer case_count: direct assigned cases of all statuses, no descendants, excluding other-workspace or other-project cases (legacy projectless cases remain included). Counts are not limited by fetched membership rows. API-key callers require test_runs:read for backward compatibility with execution workers.
• get_test_suite — Read one test suite directly with required id (UUID). Returns the suite record only, without implicitly loading child suites or member test cases. Requires access to its workspace and project; API-key callers require test_runs:read.
• create_test_suite — Create a suite in the required project returned by list_projects. Nests up to 3 levels via parent_suite_id. API-key callers require test_cases:write.
• update_test_suite — Update by suite UUID: id, optional name (trimmed, 1-120 characters), nullable description (max 50000 characters), and status (active/archived). Omitted fields and case membership are preserved. Requires active contributor-or-higher project access and test_cases:write. Parent moves and pinning are not supported; parent moves require atomic descendant-depth maintenance. Returns id, team_id, project_id, name, description, parent_suite_id, depth, status and updated_at. Example: {"id":"suite-uuid","name":"Checkout regression","description":null}.
• list_test_runs — List test runs with suite name, assignee, and pass/fail summary.
• create_test_run — Create a dashboard-managed suite run. Running a parent suite automatically includes every case in every descendant sub-suite (a case linked to both is added exactly once). Each test_run_results row records which originating sub-suite the case came from, so result pages can group by origin.

External Agent Execution

These tools let Hermes or another agent runtime execute an approved suite without becoming the QA system of record. Use a workspace-scoped key with only test_runs:read and test_runs:write. The suite supplies the project boundary; callers cannot override it.

• start_test_plan — Start or resume an immutable suite snapshot with a stable external_run_id. A repeated ID returns the existing matching run and first page instead of creating a duplicate.
• get_test_run_plan — Read canonical run state and a stable plan page. Pass the previous next_cursor; pages default to 100 cases and are capped at 200.
• report_test_results — Submit 1–200 results with passed, failed, blocked, or skipped status. Exact retries are safe; trying to overwrite a case with another status is rejected.
• abort_test_run — Idempotently stop an interrupted run while preserving accepted partial results and the canonical summary.

Quota behavior: retry start_test_plan with the same external_run_id to resume the matching run without consuming another run. Deleting data does not reset monthly run usage.

Runtime boundary: case snapshots exclude credentials, file bodies, and private attachment paths. Result evidence is text in the MVP. Target credentials stay in the execution runtime. Browser, model, and network costs remain customer-side, and customers must restrict target access and network egress. A human remains responsible for defect and release decisions.

The Hermes Agent guide packages this loop as a bugAgent-maintained community skill. The public starter kit contains a copy-ready config and installable skill. It is not an official Nous Research integration.

Reports (Tier 1 + Tier 4 analytics)

• get_test_reports_overview — Headline KPIs for a window (pass rate, runs completed, cases executed) with deltas vs the prior equivalent window. Same numbers the Reports tab KPI strip shows. This does not create a saved Project Report. Enterprise XLSX Project Reports and their schedules are managed in the dashboard; no MCP tool is enabled for those saved artifacts in this release.
• get_test_reports_failures — Four "what to fix?" lists: failing_cases (≥50% fail, min 3 runs), flaky_cases (most pass/fail flips), failing_suites (≥30% fail, min 5 runs), regressed_cases (most-recent fail with an earlier pass in the window).

Example Workflow

1. create_test_case_folder → make a folder tree (e.g. Smoke → Auth). Use the returned folder ID when creating a test case in the same project; the dashboard's New Test Case form also offers inline folder creation.
2. create_test_case → define cases; edit content with update_test_case, organize suite membership with bulk_update_test_cases
3. Example tools/call: {"name":"update_test_case","arguments":{"id":"00000000-0000-4000-8000-000000000001","title":"Verify login rejection","steps":[{"action":"Submit an incorrect password","expected":"An error is shown; no session is created"}],"status":"active","folder_id":null}}. Omitted priority, type, and description remain unchanged.
4. create_test_suite → build a test plan (sub-suites optional, up to 3 levels deep)
5. create_test_run → create a human/dashboard-managed run from a parent suite — sub-suites auto-included
6. start_test_plan → start or resume a retry-safe external-agent run
7. get_test_run_plan → retrieve every immutable plan page, then execute it in the selected runtime
8. report_test_results → return bounded result batches; call abort_test_run if execution cannot continue safely
9. get_test_reports_failures → ask "what to fix this week?" once the run completes
10. get_test_reports_overview → track the pass-rate trend week over week

⚡

Team Booster

• scale_team — Instantly scale your QA team with booster testers. Accounts are provisioned automatically with tester access. Specify team_size (1–10), location, duration, budget, and optionally product_url, product_types, and tech_levels. Available on the Enterprise plan. You will not be charged until approval has been given.

Example Workflow

1. scale_team → provision 5 senior testers in the US for 1 month
2. list_team_members → verify new testers appear in your team
3. list_bug_reports → review reports filed by booster testers

📱

Mobile Testing (Enterprise)

Mobile resources are project-scoped. Pass project_id or a flexible project selector on creates, imports, and filtered lists. Automations inherit the linked app’s project; otherwise the server uses the workspace default project. Unfiltered lists may still include legacy workspace-level rows until they are migrated.

• list_mobile_apps — List uploaded apps with optional project_id / project, platform, and limit filters. Returns each app’s project_id so agents can keep subsequent operations in the same project.
• upload_mobile_app — Register an APK (Android) or IPA (iOS) app for testing on real devices. Requires name, platform (android / ios), and file_url; pass project_id to assign it to the active project. For iOS, upload the IPA for real-device runs, then use the dashboard to upload a simulator .app build for recording.
• update_mobile_app — Replace an app binary with a new version. Clears cached URLs and simulator builds so all automations use the new version on next run. Requires app_id and file_url. Optional: version. Private linked login profiles require their active creator; shared profiles require active access to the same project. Schedules inherit the protected automation default.
• list_mobile_automations — List mobile automations with optional project_id / project, app_id, status, and limit filters. Results include project_id and the linked app ID.
• create_mobile_automation — Create a test script. Requires name, app_id, script_type (maestro for YAML, appium for Appium Python, appium_js for Appium JavaScript), and script; pass project_id when the app is not already project-scoped. For one externally validated, self-contained Maestro YAML flow, set execution_mode to browserstack_maestro; otherwise it defaults to appium_actions. The YAML appId must match the linked app’s stored package or bundle ID; if none is stored, the first validated native flow establishes it. Placeholder app IDs and obfuscated Android resource IDs are rejected. Inline runFlow is supported, but external flow/script file references are rejected in v1. Native Maestro preserves commands such as inputRandomText and copyTextFrom plus runtime expressions such as ${maestro.copiedText} and ${output.value}. A same-project credential_id may supply complete inputText values of ${USERNAME} / ${PASSWORD}. A same-project variable_profile_id may save the default for referenced ${DATA_*} values; every referenced key must exist. Data profiles are non-secret synthetic data only.
• import_mobile_script — Import an existing mobile test script and turn it into a runnable automation, preserving the developer’s own locators so runs resolve elements precisely. Supported dialects: Appium‑Python, WebdriverIO, Maestro (YAML flows), and Playwright (mobile‑web). Obfuscated Android resource-ID placeholders are skipped and reported in selector-mapping warnings. Android apps only. Requires name, app_id, and script; optional target_devices and project_id. Returns the automation plus action_count, detected dialect, and selector-mapping warnings.
• run_mobile_automation — Start a mobile automation on a real device. Requires automation_id; optional device, os_version, credential_id, and native-Maestro variable_profile_id. For data, omit variable_profile_id to inherit the automation default, pass null to use no profile, or pass a same-project UUID to override. Every referenced ${DATA_*} key must exist. A private login profile requires its active creator; a shared login profile requires active same-project access. Exact known credential values are filtered and exact data-profile values receive best-effort filtering from persisted textual evidence; transformed, partial, encoded, or app-derived data values may remain. Authorized private video/screenshots remain available and may show values rendered by the tested app, so data profiles must contain only synthetic non-secret values. If credential redaction context is unavailable or sanitization cannot be proven safe, detailed credentialed text is withheld while status and available visual evidence remain. Diagnostics require workspace and project authorization; media links expire after five minutes.
• list_mobile_runs — Get authorized mobile run results (status, device, result summary, private video and screenshot links, BrowserStack session, filtered credentialed native Maestro logs and failures when safely available, and any auto-created bug). Workspace membership and project access are enforced for run diagnostics. Optional filters: project_id, automation_id, status (queued, running, passed, failed, error, archived), and limit. Archived runs are excluded by default.
• create_login_profile — Create a write-only encrypted username/password profile reusable by Mobile, Web Automation, and Exploratory AI. Requires project_id, name, username, and password; optional visibility is private (default) or shared. Private profiles are creator-only. Shared profiles are usable by active members with access to the same project.
• create_mobile_credential — Compatibility name for create_login_profile; uses the same inputs and security boundary.
• list_login_profiles — List only profiles visible to the caller, optionally for one project_id. Returns non-secret metadata including visibility; private profiles owned by other users and inaccessible projects are omitted.
• list_mobile_credentials — Compatibility name for list_login_profiles; never returns credential secrets.
• update_login_profile — Rename, rotate, or change visibility. The active creator may update any field. An active workspace owner/admin may rename or rotate a shared profile but cannot change visibility; private profiles remain creator-only.
• update_mobile_credential — Compatibility name for update_login_profile; uses the same ownership and project checks.
• delete_login_profile — Creator soft delete, with owner/admin lifecycle recovery for shared profiles only. Future-use defaults are cleared while audit history remains.
• delete_mobile_credential — Compatibility name for delete_login_profile; historical references remain for audit.
• create_mobile_variable_profile — Create reusable, project-scoped synthetic test data with project_id, name, and a variables object such as {"DATA_EMAIL":"qa@example.test","DATA_REGION":"ca"}. Keys must be uppercase DATA_* identifiers. Profiles allow 1–100 strings, 4096 UTF-8 bytes per value, and 65536 bytes total. Reserved credential/runtime names are rejected. Never store credentials, tokens, production personal data, or other secrets.
• list_mobile_variable_profiles — List Mobile/Both profiles and their readable non-secret values for one authorized project_id. Project assignment rules apply. Existing profiles and mobile creation default to both; create/update accept platform (mobile or both). Web-only profiles are excluded from mobile catalog access and runtime use.
• update_mobile_variable_profile — Rename a profile or replace its complete variables object by id. Only the active creator or an active workspace owner/admin may update it.
• delete_mobile_variable_profile — Soft-delete a profile by id. Only the active creator or an active workspace owner/admin may delete it; automation defaults are cleared while historical run references remain.
• list_mobile_schedules, create_mobile_schedule, delete_mobile_schedule — List, create, and remove real-device schedules. Schedules inherit project context, login profile, and non-secret variable profile from their selected automation. Private login profiles require their active creator; shared login profiles require active same-project access. Non-secret variable profiles retain their creator-or-owner/admin policy. Schedule changes and deletion are restricted to the active schedule creator or an active workspace owner/admin.

Web Test Data Catalog

The same non-secret project catalog is available from Automate Web. These tools require the workspace’s automation entitlement and automations:write API-key scope, including reads. They do not require Mobile access. Values never share records with encrypted Login Profiles. Catalog support does not yet bind or inject profile values into web runs.

• create_web_variable_profile: required project_id, name, variables; optional platform (web or both), default web. Uses the same DATA_* limits as mobile. Returns the profile, including its platform.
• list_web_variable_profiles: required project_id; returns { profiles: [...] } containing Web/Both records only.
• get_web_variable_profile: required id; returns an accessible Web/Both profile and its synthetic values.
• update_web_variable_profile: required id; optional name, complete replacement variables, or platform (web or both). Requires the active creator or active workspace owner/admin. To narrow Both to Mobile, use the Mobile catalog with Mobile access.
• delete_web_variable_profile: required id; same management permissions. Soft-deletes and returns { deleted: true }, retaining audit history.

Example: resolve a project using list_projects, call create_web_variable_profile with {"project_id":"PROJECT_UUID","name":"Canadian checkout","platform":"both","variables":{"DATA_REGION":"CA"}}, then verify it with list_web_variable_profiles. Inaccessible projects/profiles fail without exposing their values; invalid data or duplicate project-wide names are rejected.

Example Workflow — Android

1. list_projects → resolve the target project_id
2. upload_mobile_app → register the APK in that project
3. Record securely in the dashboard, or use import_mobile_script / create_mobile_automation
4. list_mobile_automations → resolve the automation in the same project
5. run_mobile_automation → trigger it on a real device, optionally with a login profile
6. list_mobile_runs → check status, result summary, private visual links, and BrowserStack session metadata
7. Failures auto-create bug reports with failure snapshot and step breakdown

Example Workflow — iOS

1. upload_mobile_app → register your IPA with project_id for real-device runs
2. Upload simulator .app build on app detail page (for recording)
3. Record test in browser → actions captured from simulator
4. run_mobile_automation → trigger the saved automation on an iPhone (uses the IPA)
5. update_mobile_app → replace IPA with new version when ready

Example Workflow — Native Maestro

1. upload_mobile_app → register the APK or IPA in the target project
2. create_mobile_credential → optionally create a same-project profile for an authenticated flow
3. create_mobile_variable_profile → optionally create same-project synthetic DATA_* values used by the flow
4. create_mobile_automation → pass one known-working YAML flow with the linked app’s exact package/bundle appId, script_type: maestro, and execution_mode: browserstack_maestro. Use ${USERNAME} / ${PASSWORD} for login and ${DATA_EMAIL} -style placeholders for synthetic input; pass profile IDs to save defaults.
5. run_mobile_automation → select a compatible device and optionally override the login or variable profile. Omit the variable profile to inherit, or pass null to disable it for one run.
6. list_mobile_runs → inspect authorized pass/fail summaries, private video/screenshots, filtered logs, real step names, detailed failures, and session metadata. If safe sanitization cannot be established for a credentialed run, detailed text is withheld while status and available visual evidence remain.

Refine with AI: the allowlisted beta is available through the dashboard and REST refinement endpoints. No Refine MCP tools are part of the public catalog yet.

✅

Compliance & Evidence (Enterprise)

• collect_compliance_evidence — Trigger automated evidence collection from connected services (Cloudflare, GitHub, Sentry, Supabase, Railway). Returns run ID. Collects SSL/TLS settings, WAF status, Dependabot alerts, error trends, deploy history, and more.
• check_config_drift — Check all connected services for security configuration drift from baselines (SSL mode, TLS version, HSTS, WAF rules, security headers).
• generate_access_review — Create a quarterly access review report. Audits team members, roles, MFA status, API key usage, and generates recommendations (e.g., revoke inactive keys).
• get_security_events — Query the cross-service security event timeline. Filter by source (cloudflare, sentry, github) and severity (critical, high, medium, low, info). Events are auto-correlated across services.

Compliance Coverage

These tools help with SOC2 (CC4.1, CC6.1, CC7.2, CC8.1), ISO 27001 (A.5.18, A.8.8, A.8.9, A.8.15-16, A.8.29), and GDPR (Art. 5, 25, 32, 33) compliance requirements.

Compatible Clients

bug Agent works with any client that supports the Model Context Protocol. Here are setup guides for popular clients:

Open Settings → Developer → Edit Config, then add:

{
  "mcpServers": {
    "bugagent": {
      "type": "http",
      "url": "https://mcp.bugagent.com/mcp",
      "headers": {
        "Authorization": "Bearer ba_live_YOUR_KEY_HERE"
      }
    }
  }
}

Restart Claude Desktop after saving.

✳️

Cursor

Open Settings → MCP Servers → Add Server, or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "bugagent": {
      "type": "http",
      "url": "https://mcp.bugagent.com/mcp",
      "headers": {
        "Authorization": "Bearer ba_live_YOUR_KEY_HERE"
      }
    }
  }
}

🌊

Windsurf

Open Settings → MCP → Add Server, or edit your MCP config file:

{
  "mcpServers": {
    "bugagent": {
      "type": "http",
      "url": "https://mcp.bugagent.com/mcp",
      "headers": {
        "Authorization": "Bearer ba_live_YOUR_KEY_HERE"
      }
    }
  }
}

Add bug Agent directly from the terminal:

claude mcp add --transport http bugagent https://mcp.bugagent.com/mcp --header "Authorization: Bearer ba_live_YOUR_KEY_HERE"

This connects directly to the hosted Streamable HTTP server.

For clients that require stdio, use the published bugagent-mcp bridge:

• Command: npx
• Command line: npx -y bugagent-mcp
• Args: ["-y", "bugagent-mcp"]
• Env: BUGAGENT_API_KEY

Get Help

Need assistance? We're here to help.

Discord Community

Join our Discord for real-time support and community discussions.

Email Support

support@bugagent.com — We typically respond within 24 hours.