MCP
Connect bugAgent 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 bugAgent handles the rest.
Getting Started
The bugAgent 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 bugAgent's cloud API.
Sign up at app.bugagent.com and generate an API key from the console.
Add bugAgent as an MCP server in your client's config (see setup below).
Describe a bug in natural language and bugAgent 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
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, bugAgent 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 bugAgent console.
MCP Client Configuration
Add the following to your MCP client's configuration file:
{
"mcpServers": {
"bugagent": {
"command": "npx",
"args": ["-y", "@bugagent/mcp-server"],
"env": {
"BUGAGENT_API_KEY": "ba_live_your_key_here"
}
}
}
} ba_live_your_key_here with your actual API key from the console.MCP Features
The bugAgent 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). Setformat_description: trueto auto-reformat the description into a structured template using AI. Passtime_spent_secondsto track QA effort.list_bug_reports— List and filter reports (max 100 per page)get_bug_report— Get full details of a report by ID. ReturnsqualityScore(integer 1–10) andqualityBreakdown(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 (includestime_spent_secondsfor timer tracking)classify_bug— Classify a description into one of 19 report types (bugs, features, enhancements, etc.) with confidence scoreflush_reports— Bulk delete old reports (admin only)
Usage & Analytics
get_usage— Check usage against plan limitsget_stats— Daily counts, type/severity/status breakdowns
Project Management
list_projects— List available projectscreate_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
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 namechange_password— Change account passwordget_settings/update_settings— Manage preferences
API Key Management
generate_api_key— Create a named API keylist_api_keys— List active keys (prefix only)regenerate_api_key— Revoke and replace a keydelete_api_key— Permanently revoke a key
Team Management
list_team_members— List all members of your organization with roles, status, and booster flagsinvite_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 connectionpush_to_claude— Send a bug report to Claude for root cause analysis. Returns detailed analysis including probable cause, suggested fix, verification steps, and risk assessment. Requires Claude connection configured in Settings → Integrations.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. Pro/Team/Enterprise plans onlyrun_performance_test— Trigger a page audit and load test, or a mobile app profiling session on real Android/iOS devices via BrowserStack. Returns a run ID to poll for resultsget_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 teamget_performance_usage— Check monthly performance test usage against plan limits. Free=0, Pro=1/mo, Team=2/mo, Enterprise=10/mo. Top-up: 5 tests for $499
Example Workflow
get_performance_usage→ check remaining quotacreate_performance_test→ configure a test for your URLrun_performance_test→ trigger the audit + load testget_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. Pro/Team/Enterprise plans onlyrun_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 resultsget_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 guidancelist_security_scans— List all security scan configurations for the current team with last score and auth/depth badgesget_security_usage— Check monthly security scan usage against plan limits. Pro=2/mo, Team=5/mo, Enterprise=20/mo. Top-up: 10 scans for $299
Example Workflow
get_security_usage→ check remaining quotacreate_security_scan→ configure a scan for your URL or reporun_security_scan→ trigger the vulnerability scanget_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. Team/Enterprise onlyget_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 numbersget_code_review_usage— Check code review usage. Unlimited on Pro, Team, and Enterprise plansget_code_review_analytics— Get review analytics: trends, finding categories/sources, severity breakdown, velocity metrics, top repos/authors. Supports 7/30/90-day lookbacklist_explorations— List Exploratory AI configs for the teamcreate_exploration— Create a new autonomous exploration targeting a URLget_exploration— Get exploration config with recent runsget_exploration_run— Get run results with all phase data and findingsget_exploration_usage— Check monthly Exploratory AI usage (Pro: 3/mo, Team: 10/mo, Enterprise: 50/mo)
Example Workflow
get_code_review_usage→ check remaining reviews- Review a PR in the dashboard at
/dashboard/code-review list_code_reviews→ see recent reviewsget_code_review→ get findings and suggestions
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. Setvisibilitytoprivateorshared. Auto-title from first 30 characters if no title provided. Passtime_spent_secondsto track QA effort.get_note— Get full note details including content and attachments. Requiresid.update_note— Update title, content, format, visibility, project, ortime_spent_seconds. Only the author can update. Requiresid.delete_note— Permanently delete a note and its attachments. Only the author can delete. Requiresid.
Example Workflow
create_note→ start a testing session noteupdate_note→ append observations as you testlist_notes→ search past notes by keyword or projectget_note→ retrieve full note with attachments
Automation
create_automation— Create a new automation with a custom Playwright script (no FAB recording required). Requiresname. Optional:target_url,script(Playwright test content; defaults to a placeholder),status(draftoractive, default:draft),project_id. Returns the automationid. Pro/Team plan required. Tip — Duplicate an automation: useget_automationto fetch the original script, then callcreate_automationwithnameset to"[Copy] Original Name"and pass the originalscript,target_url, andproject_id. The duplicate starts indraftstatus with no version history.list_automations— List Playwright automation scripts. Filter byproject_idorstatus(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. Requiresid. Returns automation with script code and recent_runs array.run_automation— Trigger an immediate run of a Playwright test. Requiresautomation_id. Virtual mode (default): optionaldevicefor viewport emulation (e.g.desktop,iphone-15). Live mode: setbrowserstack: truewithbs_browser(chrome,firefox,safari,edge),bs_os(Windows,OS X), andbs_os_versionto run on a real browser. Video, console logs, and network logs captured automatically.list_automation_runs— List recent runs for an automation. Requiresautomation_id. Returns runs with status, duration_ms, and error_message.list_schedules— List all scheduled automation runs for the current team with cron expression, timezone, and notification settings.create_schedule— Create a scheduled automation run. Requiresautomation_idandcron_expression. Optionaldeviceparameter selects the device to emulate — e.g.desktop,iphone-15,galaxy-s23,ipad. Default:desktop. Also supportstimezone,notify_on_fail,notify_email, and Slack notification options.delete_schedule— Delete a scheduled automation run. Requiresid.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. Requiresautomation_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. Requiresautomation_id. Returns the restored script and the number of versions remaining.
Example Workflow
create_automation→ create a test with a custom scriptlist_automations→ browse available testsget_automation→ inspect the Playwright scriptrun_automation→ trigger the testlist_automation_runs→ check results and duration
Time Tracking
list_time_entries— List time entries for the team. Filter byperiod(today,week,month,all),project_id,category, andsort(newest,oldest,most_time,least_time). Team plan only.create_time_entry— Log time spent on QA tasks. Requiresdescription,category, andduration_minutes. Optionally setproject_idandentry_date(defaults to today). Team plan only.update_time_entry— Update an existing time entry. Requiresid. Can updatedescription,category,duration_minutes,project_id, orentry_date. Team plan only.delete_time_entry— Permanently delete a time entry. Requiresid. Team plan only.
Example Workflow
create_time_entry→ log 45 minutes of regression testinglist_time_entries→ view this week's time entriesupdate_time_entry→ adjust duration or categorydelete_time_entry→ remove an incorrect entry
Test Cases
list_test_cases— List test cases with optionalsearch,priority(critical,high,medium,low),type(functional,regression,smoke,integration,e2e,performance,security,usability,accessibility),status(active,draft,deprecated), andsort(newest,oldest,name,priority). Returns test cases with steps count, tags, and priority.create_test_case— Create a test case with detailed steps. Requiresname. Optional:description,preconditions,steps(array of{ action, expected }),priority,type,tags,estimated_time(seconds). Returns the created test case with all steps.get_test_case— Get full test case details including steps and execution history. Requiresid.list_test_suites— List test suites with case count and last run status. Optionalsearchfilter.create_test_suite— Create a test suite to group related test cases. Requiresname. Optional:description.list_test_runs— List test runs with suite name, assignee, and pass/fail summary. Filter bysearch,status(in_progress,completed), orsuite_id.create_test_run— Create a test run from a suite. Requiressuite_idandname. Optional:assigned_to(user UUID). Snapshots all cases from the suite at creation time.
Example Workflow
create_test_case→ define a test case with stepscreate_test_suite→ group related test casescreate_test_run→ start a run from the suitelist_test_runs→ check run progress and pass rate
Team Booster
scale_team— Instantly scale your QA team with booster testers. Accounts are provisioned automatically with tester access. Specifyteam_size(1–10),location,duration,budget, and optionallyproduct_url,product_types, andtech_levels. Pro and Team plans only. You will not be charged until approval has been given.
Example Workflow
scale_team→ provision 5 senior testers in the US for 1 monthlist_team_members→ verify new testers appear in your teamlist_reports→ review reports filed by booster testers
Geo-Snap
create_geo_snap— Capture screenshots of a URL from multiple countries simultaneously. Requiresurl(string) andcountries(array of country codes, e.g.["US", "DE", "JP"]). Free plan: 1 country per capture, 10 saved screenshots. Pro/Team: up to 5 countries, unlimited saved screenshots. Returns an array of snap objects withid,url,country,screenshot_url,status, andcreated_at.
Example Workflow
create_geo_snap→ capturehttps://example.comfrom US, DE, and JP- Compare screenshots to verify localization, geo-redirects, and compliance
Mobile Testing
upload_mobile_app— Upload an APK (Android) or IPA (iOS) app for testing on real devices. Requiresname,platform(android/ios), andfile_url. For iOS: upload the IPA for real-device runs, then upload a simulator.appbuild 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. Requiresapp_idandfile_url. Optional:version.create_mobile_automation— Create a test script. Requiresname,app_id,script_type(maestrofor YAML,appiumfor Appium Python,appium_jsfor Appium JavaScript), andscript(the test script content).run_mobile_test— Trigger a test run on a real BrowserStack device. All script types run via the Appium 2.x W3C WebDriver protocol. Requiresautomation_idanddevice(e.g."Google Pixel 8","iPhone 15 Pro"). Returns run ID for tracking. Video, Appium logs, device logs, and network logs are collected automatically.list_mobile_runs— Get results for mobile test runs. Optional filters:automation_id,status(queued,running,passed,failed,error,archived),limit. Archived runs excluded from default listing.
Example Workflow — Android
upload_mobile_app→ upload your APK- Record test in browser → actions captured automatically
run_mobile_test→ run on Google Pixel 8 (real device)list_mobile_runs→ check results with video and logs- Failures auto-create bug reports with failure snapshot and step breakdown
Example Workflow — iOS
upload_mobile_app→ upload your IPA (for real-device runs)- Upload simulator
.appbuild on app detail page (for recording) - Record test in browser → actions captured from simulator
run_mobile_test→ run on iPhone 15 Pro (real device, uses IPA)update_mobile_app→ replace IPA with new version when ready
Compatible Clients
bugAgent 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:
{
"mcpServers": {
"bugagent": {
"command": "npx",
"args": ["-y", "@bugagent/mcp-server"],
"env": {
"BUGAGENT_API_KEY": "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": {
"command": "npx",
"args": ["-y", "@bugagent/mcp-server"],
"env": {
"BUGAGENT_API_KEY": "ba_live_your_key_here"
}
}
}
} Windsurf
Open Settings → MCP → Add Server, or edit your MCP config file:
{
"mcpServers": {
"bugagent": {
"command": "npx",
"args": ["-y", "@bugagent/mcp-server"],
"env": {
"BUGAGENT_API_KEY": "ba_live_your_key_here"
}
}
}
} Claude Code (CLI)
Add bugAgent 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 bugAgent. Use the standard configuration:
- Command:
npx - Args:
["-y", "@bugagent/mcp-server"] - Env:
BUGAGENT_API_KEY
Getting Started with CLI
The bugAgent 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:
export BUGAGENT_API_KEY=ba_live_your_key_here Or pass it directly with the --api-key flag:
bugagent reports list --api-key ba_live_your_key_here 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 <id> --body "Reproduced on v2.1" Use --help on any command for details:
bugagent reports --help
bugagent reports create --help Example Session
# 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
bugagent reports get rpt_abc123
# Sync a report to Jira
bugagent jira sync --report-id rpt_abc123
# 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
--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 bugAgent on your behalf.
AgentSkills let AI coding assistants (Claude Code, Cursor, etc.) invoke CLI tools contextually. The bugAgent 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 bugAgent commands naturally — with full knowledge of your product, testing guidelines, and uploaded documentation:
"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.
Get Help
Need assistance? We're here to help.