bugAgent MCP Server

MCP v1

Navigation

Model Context Protocol

MCP

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.

Discord Community [email protected]

Getting Started

The bug_Agent_ MCP server lets AI clients create, query, and manage bug reports, feature requests, enhancements, and more through the Model Context Protocol. It runs locally and communicates with bug_Agent_'s cloud API.

1

Get your API key

Sign up at app.bugagent.com and generate an API key from the console.

2

Configure your AI client

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

3

Start filing bugs

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

Quick Example

# 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

Install

No global install required. Use npx to run the MCP server on demand:

npx @bugagent/mcp-server

Configure your API key

When you first connect, bug_Agent_ will prompt you for your API key. You can also set it via environment variable:

export BUGAGENT_API_KEY=ba_live_your_key_here

Get your API key from the bug_Agent_ console.

MCP Client Configuration

Add the following to your MCP client's configuration file:

mcp.json

{
  "mcpServers": {
    "bugagent": {
      "command": "npx",
      "args": ["-y", "@bugagent/mcp-server"],
      "env": {
        "BUGAGENT_API_KEY": "ba_live_your_key_here"
      }
    }
  }
}

💡

Replace ba_live_your_key_here with your actual API key from the console.

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.

🔑

Get your API key first. Sign in to app.bugagent.com/dashboard/settings/api-keys, click Create API Key, and copy the value (starts with ba_live_). You’ll only see it once, so paste it somewhere safe. Every example below uses this key.

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)

Terminal

npx @modelcontextprotocol/inspector

Windows (PowerShell or CMD)

PowerShell

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. Click the Authentication tab → add a custom header:
   • Header Name: Authorization
   • Value: Bearer ba_live_YOUR_KEY_HERE
5. Click Connect. You’ll see all 60+ bug_Agent_ tools in the left panel.
6. Click any tool (e.g. list_bug_reports), fill in parameters, click Run Tool. Response shows on the right.

Prerequisites: Node.js 18 or later. Install from nodejs.org if you don’t have it.

Option 2 — Claude Desktop (Mac + Windows)

If you use the Claude Desktop app, you can add bug_Agent_ as a permanent MCP server. Claude will then have all bug_Agent_ tools available in every conversation.

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:
   claude_desktop_config.json

{  
  "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.

Terminal / PowerShell

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 using tools in any chat: “Show me my exploration usage for this month.”

To remove it later:

claude mcp remove bugagent

Option 4 — OpenAI Codex CLI

If you use the OpenAI Codex CLI, add bug_Agent_ to ~/.codex/config.toml for permanent registration, or pass the config inline for a one-off session.

Permanent registration (add to config)

~/.codex/config.toml

[[mcp_servers]]
name = "bugagent"
type = "http"
url  = "https://mcp.bugagent.com/mcp"

[mcp_servers.headers]
Authorization = "Bearer ba_live_YOUR_KEY_HERE"

Inline — one session

Terminal

codex \
  --mcp-server '{"name":"bugagent","type":"http","url":"https://mcp.bugagent.com/mcp","headers":{"Authorization":"Bearer ba_live_YOUR_KEY_HERE"}}' \
  "list the last 5 bug reports"

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. Add bug_Agent_ once and the AI assistant inside Cursor can file bugs, list reports, run scans, etc. without leaving your editor.

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:
   ~/.continue/config.json

{  
  "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 security scans.”

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. For those hosts you generate a workspace-scoped OAuth credential pair from the bug_Agent_ dashboard and paste it into the host’s connector form. The credentials are MCP-host-agnostic — any OAuth client supporting Authorization Code + PKCE can use them. The walkthrough below uses the Claude.ai web app as the most common example.

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
     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.

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

Terminal

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

# 1. List all available tools
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":"tools/list"}'

# 2. 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":2,
    "method":"tools/call",
    "params":{
      "name":"list_bug_reports",
      "arguments":{"project":"bugagent","limit":5}
    }
  }'

Windows (PowerShell)

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. List all tools
$body = '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Invoke-RestMethod -Uri "https://mcp.bugagent.com/mcp" `
  -Method Post -Headers $headers -Body $body

# 2. Call list_bug_reports for a specific project
$body = @{
  jsonrpc = "2.0"
  id = 2
  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 arrive as Server-Sent Events (the MCP Streamable HTTP standard). Each chunk is a line prefixed with data: followed by a JSON object. The Accept: application/json, text/event-stream header is required — the server rejects requests without it.

ℹ️

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

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 Reports

Ask your AI assistant

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
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

Config file locations for all eight clients. Every client connects to https://mcp.bugagent.com/mcp with the header Authorization: Bearer ba_live_YOUR_KEY_HERE over Streamable HTTP.

Client Config location / command

MCP Inspector No file — enter URL + auth header in the browser UI after npx @modelcontextprotocol/inspector

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)

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

Troubleshooting

Symptom Fix

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

Tools not showing in client Fully quit and relaunch the client after editing the config. In Claude Desktop, Cmd+Q (not just close the window). In Cursor, check Settings → MCP for a green dot.

Accept header required Direct HTTP calls must include Accept: application/json, text/event-stream — the Streamable HTTP spec requires it. The server returns 406 without it.

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 → API Keys.

Tools appear but calls fail silently Confirm the server is reachable: curl -I https://mcp.bugagent.com/health should return 200. If it times out, check network/firewall rules.

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.

Codex CLI — tools not recognized Verify ~/.codex/config.toml uses [[mcp_servers]] (double brackets, array syntax). Check Codex CLI version is recent enough to support MCP (codex --version).

MCP Features

The bug_Agent_ MCP server provides tools for:

🐛

Bug Report Management

• 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. The response includes 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, type (one of 19 dashboard categories), severity (s1-s4 or legacy critical/high/medium/low), status (using the dashboard's exact values: new, awaiting-triage, confirmed, in-progress, blocked, resolved, retesting, closed, reopened — hyphens are deliberate), resolution (fixed / duplicate / works-as-designed / cannot-reproduce / will-not-fix / need-more-info / unresolved), root_cause (open-ended kebab-case tag — common values: regression, missing-requirement, documentation, incomplete-refactor, not-a-bug, requirements-mismatch), or reporter_user_id (UUID of the team member who filed the report — call list_team_members first to resolve a name to a UUID). Each result includes reporter_user_id, project_id, project, short_id, legacy_short_id, and project_short_id so agents can link and update the correct project-scoped report.
• 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 rows in the same shape as list_bug_reports for tool composability. 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. 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 ID. ID formats: accepts either the UUID (e.g. 1fb72a2c-87c7-...), the workspace-scoped short ID (e.g. WRKID-545), or the project-scoped short ID (e.g. WRKID-APP-042). Short-ID lookups are team-scoped — guessing another workspace's short ID returns 404. Returns project_id, project, short_id, legacy_short_id, project_short_id, ticket_number, project_ticket_number, qualityScore (integer 1–10), and qualityBreakdown (object with 10 dimension scores: reproductionSteps, expectedVsActual, environmentDetails, evidence, rootCauseAnalysis, impactAssessment, contextAndHistory, heuristicsAndOracles, clarityAndStructure, actionability — each 0.0–1.0).
• update_bug_report — Update fields on an existing report. Accepts UUID or short ID (WRKID-545). Updatable fields include title, description, type (any of 19 dashboard categories), severity, priority (urgent / high / normal / low — fix urgency, independent of severity), status (matches the dashboard exactly: new, awaiting-triage, confirmed, in-progress, blocked, resolved, retesting, closed, reopened — hyphens are deliberate), resolution (fixed / duplicate / works-as-designed / cannot-reproduce / will-not-fix / need-more-info / unresolved), and root_cause (open-ended kebab-case tag — common values: regression, missing-requirement, documentation, incomplete-refactor, not-a-bug, requirements-mismatch). The agent-loop convention requires both resolution and root_cause to be set whenever status transitions out of new; the dashboard, analytics, and the future claude-bot training corpus all depend on those fields. Also includes assigned_to (user ID from list_team_members) and time_spent_seconds for timer tracking. Changing assigned_to automatically triggers the in-app bell notification AND a courtesy email to the new assignee (respecting their per-user opt-out in Account Settings — same pipeline as the dashboard endpoints).
• 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.
• list_comments — List a report's full comment thread, oldest first — each comment with author name, parentId (threaded replies), and timestamps. Comments are not part of get_bug_report, so this is how you read a ticket's discussion. Accepts UUID or short ID.
• link_bug_reports — Create a directional semantic link between two bug reports in the same workspace. link_type is one of duplicate-of, parent-of, related-to, or depends-on. The inverse perspectives (duplicated-by / subtask-of / blocks) are derived at read time — only one row needs to be stored. Both from_report_id and to_report_id accept UUIDs or short IDs (WRKID-545).
• 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. 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
• get_stats — Daily counts, type/severity/status breakdowns

📁

Project Management

• list_projects — List available projects with id, name, slug, ticket_prefix, description, and default status. Use those values with create_bug_report and list_bug_reports 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 / update_settings — Manage preferences

🔑

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_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

• sync_to_jira — Sync a report to Jira using team's shared connection
• 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 — Upgrade subscription via Stripe

⚡

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

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

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
• get_exploration — Get exploration config with agent settings and recent runs
• 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)

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 search, project filter, author filter, and date range. Returns notes the user owns or shared notes within the team.
• create_note — Create a note in one of 5 formats: markdown, plain_text, rich_text, 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.

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. Team plan required. 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. Virtual mode (default): optional device for viewport emulation (e.g. desktop, iphone-15). Live 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. Live 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. 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: pass optional version_index (integer, 0-indexed) to execute a prior entry from the automation's script_versions history. Default: when version_index is omitted or null, the current live script runs — don't pass a placeholder value just to "pick current". Out-of-range, negative, or non-integer values are rejected. 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 cron, timezone, device, and notification settings
• create_schedule — Create a scheduled web automation run. Requires automation_id and cron_expression. Supports device, timezone, notify_on_fail (email/slack/both), and Slack channel options. BrowserStack Live on scheduled runs: pass browserstack: true with bs_browser, bs_os, and bs_os_version — same device matrix as run_automation (Node = desktop + real Android + real iPhone; Python = desktop only).
• 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, cron_expression, and devices array
• 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 10 previous versions are retained. Requires automation_id. Returns the restored script and the number of versions remaining.

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). Team 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). Team plan only.
• update_time_entry — Update an existing time entry. Requires id. Can update description, category, duration_minutes, project_id, or entry_date. Team plan only.
• delete_time_entry — Permanently delete a time entry. Requires id. Team plan only.

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

Full test management with hierarchical folders, nested suites (up to 3 levels deep with sub-suite auto-expansion on runs), drag-drop reorder, AI-assisted case generation, 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.

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 test cases with optional search, priority (critical, high, medium, low), type (functional, regression, smoke, integration, performance, security, usability, exploratory), status (active, draft, deprecated), and sort (newest, oldest, name, priority).
• create_test_case — Create a test case. 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 (the platform stores them independently so a tester switching template_type later doesn't lose either side's data). Optional urls array (max 10 http/https URLs) attaches reference links. Requires name. Optional: description, preconditions, template_type, steps, text_content, urls, priority, type, tags, estimated_time (seconds). File attachments are uploaded via the dashboard's POST /api/test-cases/:id/attachments endpoint (multipart) — not yet exposed as an MCP tool.
• get_test_case — Get full test case details including steps and execution history.
• list_test_case_folders — List the team's folders (one folder per case via folder_id; distinct from suites, which are many-to-many test-plan groupings). Capped at 500; honors project_id and parent_folder_id filters (use "root" for top-level only).
• create_test_case_folder — Create a folder (nests up to 3 levels via parent_folder_id). Use bulk_update_test_cases to move cases into it.
• bulk_update_test_cases — Apply one action to up to 500 cases at once: set_priority, set_status, set_type, add_tags, remove_tags, add_to_suite, pin, unpin.
• link_test_case_to_bug — Establish traceability between a test case and a bug report (verified_by, covers, or relates).
• 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 (dashboard UI + REST): upload a zip export of Figma frames (up to 100 MB), Claude analyzes each screen and drafts test cases into a folder you pick or create. Multi-pass pipeline (classify → per-screen cases → flow-level cases across shared-prefix screens → self-critique) with prompt caching, 429 retry, and per-frame error isolation so one bad frame doesn't fail the batch. 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. Endpoints: POST /api/test-cases/import/figma/request, POST /api/test-cases/import/figma/start, GET /api/test-cases/import/figma/:id.

Suites & Runs

• list_test_suites — List test suites with case count and last run status.
• create_test_suite — Create a suite. Nests up to 3 levels via parent_suite_id.
• list_test_runs — List test runs with suite name, assignee, and pass/fail summary.
• create_test_run — Snapshot a suite into a new 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.

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.
• 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).

1. create_test_case_folder → make a folder tree (e.g. Smoke → Auth)
2. create_test_case → define cases; move them into folders with bulk_update_test_cases
3. create_test_suite → build a test plan (sub-suites optional, up to 3 levels deep)
4. create_test_run → snapshot a run from a parent suite — sub-suites auto-included
5. get_test_reports_failures → ask "what to fix this week?" once the run completes
6. 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 Team plan. You will not be charged until approval has been given.

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_reports → review reports filed by booster testers

📱

Mobile Testing

• upload_mobile_app — Upload an APK (Android) or IPA (iOS) app for testing on real devices. Requires name, platform (android/ios), and file_url. For iOS: upload the IPA for real-device runs, then upload a simulator .app build on the app detail page to enable 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.
• 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 (the test script content).
• list_mobile_runs — Get results for mobile test runs (status, device, video, BrowserStack session, and any auto-created bug). Mobile runs are triggered from the dashboard or on a schedule. Optional filters: automation_id, status (queued, running, passed, failed, error, archived), limit. Archived runs excluded from default listing.

Example Workflow — Android

1. upload_mobile_app → upload your APK
2. Record test in browser → actions captured automatically
3. Trigger the run on a real device (e.g. Google Pixel 8) from the dashboard or a schedule
4. list_mobile_runs → check results with video and logs
5. Failures auto-create bug reports with failure snapshot and step breakdown

Example Workflow — iOS

1. upload_mobile_app → upload your IPA (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. Trigger the run on a real device (e.g. iPhone 15 Pro, uses the IPA) from the dashboard or a schedule
5. update_mobile_app → replace IPA with new version when ready

✅

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:

🤖

Claude Desktop

Open Settings → Developer → Edit Config, then add:

claude_desktop_config.json

Restart Claude Desktop after saving.

✳️

Cursor

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

.cursor/mcp.json

🌊

Windsurf

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

mcp_config.json

💻

Claude Code (CLI)

Add bug_Agent_ directly from the terminal:

claude mcp add bugagent -- npx -y @bugagent/mcp-server

Set your API key with export BUGAGENT_API_KEY=ba_live_... before launching.

🔧

Other MCP Clients

Any client supporting MCP stdio transport works with bug_Agent_. Use the standard configuration:

• Command: npx
• Args: ["-y", "@bugagent/mcp-server"]
• Env: BUGAGENT_API_KEY

CLI

Getting Started with CLI

The bug_Agent_ CLI gives you full control over bug reports, feature requests, projects, and integrations from your terminal. Use it to:

• Automate workflows — Integrate bug reporting into CI/CD pipelines, scripts, and cron jobs
• Bulk operations — List, filter, and manage reports without leaving your terminal
• Pipe-friendly output — JSON, YAML, and raw formats for composing with jq, yq, and other tools
• Fast iteration — No browser needed — create and update reports in seconds

Installation

npm install -g @bugagent/cli

Verify the installation:

bugagent --version

Authentication

Set your API key as an environment variable:

Or pass it directly with the --api-key flag:

bugagent reports list --api-key ba_live_your_key_here

🔑

Get your API key from the bug_Agent_ console. Keys start with ba_live_.

For persistent auth, add the export to your shell profile (~/.bashrc, ~/.zshrc, etc.).

Usage

Commands follow the pattern:

bugagent <resource> <action> [flags]

Resources can also use colon syntax for subresources:

bugagent reports comments add --report-id WRKID-545 --body "Reproduced on v2.1"

Use --help on any command for details:

bugagent reports --help
bugagent reports create --help

Example Session

Terminal

# List your projects
bugagent projects list

# Create a bug report in your default project
bugagent reports create \
  --title "Checkout 500 on discount code" \
  --description "Applying SAVE20 returns HTTP 500" \
  --severity critical \
  --type logic

# View recent reports
bugagent reports list --limit 5 --format pretty

# Get full details on a report (use the short ID or UUID)
bugagent reports get WRKID-545

# Sync a report to Jira
bugagent jira sync --report-id WRKID-545

# Check your usage
bugagent usage get --format json

CLI Features

The CLI provides commands for:

reports Create, list, get, update, and flush bug reports

projects Create, list, update, and delete projects

keys Generate, list, regenerate, and revoke API keys

jira Connect, sync reports, and configure Jira settings

usage Check current usage against plan limits

stats View analytics and breakdowns

profile View and update your profile and settings

auth Login, register, and manage credentials

Global Flags

Flag Description

--api-key <key> Override the API key for this command

--format <fmt> Output format: json, yaml, pretty, raw

--debug Show request/response details for troubleshooting

--help Show help for any command

--version Print the CLI version

Output Formats

The CLI supports multiple output formats for different use cases:

json

Machine-readable JSON. Ideal for piping to jq or other tools.

yaml

Human-friendly YAML output for config files and readability.

pretty

Default. Colorized, formatted output designed for the terminal.

raw

Unformatted output. Useful for scripting and automation.

Filtering with --transform

Use --transform with GJSON syntax to query and filter output data:

# Default pretty output
bugagent reports list

# JSON for piping to other tools
bugagent reports list --format json

# YAML
bugagent reports list --format yaml

# Raw (no formatting)
bugagent reports get rpt_abc123 --format raw

# Filter with GJSON syntax
bugagent reports list --format json \
  --transform "items.#(severity==critical).title"

AI Skill

The CLI is also available as an AgentSkill, allowing AI coding assistants to use bug_Agent_ on your behalf.

✨

What is an AgentSkill?

AgentSkills let AI coding assistants (Claude Code, Cursor, etc.) invoke CLI tools contextually. The bug_Agent_ skill gives your AI assistant the ability to file bugs, check project status, and sync to Jira — all without you typing a command.

Install the Skill

claude skills install bugagent --from @bugagent/mcp-server

Once installed, the context-aware AI Assistant can use bug_Agent_ commands naturally — with full knowledge of your product, testing guidelines, and uploaded documentation:

AI Assistant Prompt

"File a critical bug: the payment webhook is returning
a 403 after the latest deploy. It affects all Stripe
events. Assign it to the payments project."

The skill translates the natural language into the appropriate CLI commands and executes them.

🎬

Session Replay + AI Assistant: When Session Replay is enabled (Team plan), the AI Assistant can reference the captured user session — clicks, navigation, errors, and network failures from the last 60 seconds — to auto-draft richer, more accurate bug reports with full reproduction context.

Get Help

Need assistance? We're here to help.

Discord Community

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

Email Support

[email protected] — We typically respond within 24 hours.