Stop Context-Switching Between Your Bug Tracker and Your Editor

You're deep in a coding session when a bug report comes in. You switch tabs, open the dashboard, copy the error description, paste it into Claude Code, switch back to grab the screenshot URL, paste that too — and by the time you've assembled enough context to actually fix anything, you've lost your flow entirely.

The Bugoon MCP Server eliminates that context switch. Once connected, Claude Code and Cursor can pull bug reports, read screenshots, and update statuses without you ever leaving your editor. This guide gets you from zero to connected in five minutes.

Prerequisites Checklist

Before writing a single line of config, confirm you have the following:

A Bugoon account — sign up free at bugoon.com if you haven't already.
At least one project created — go to the Dashboard, click New Project, and give it a name. This generates the API key your widget uses to submit reports.
Your Secret Key — navigate to Dashboard > Settings > API Keys. You'll see a Secret Key (distinct from the public API key embedded in the widget). Copy it now and keep it somewhere safe — this is the credential your MCP server will use.

You also need Node.js 18 or later installed locally. Run node -v to confirm. That's it — no global npm install is required because the config uses npx to pull the package on demand.

Step 1: Write Your .mcp.json

Create a file called .mcp.json in the root of your project (the same directory as your package.json or equivalent). Paste in the following, replacing the placeholder value with your actual Secret Key:

{
  "mcpServers": {
    "bugoon": {
      "command": "npx",
      "args": ["-y", "@rubyjobs-jp/bugoon-mcp-server"],
      "env": {
        "BUGOON_SECRET_KEY": "YOUR_SECRET_KEY",
        "BUGOON_API_URL": "https://bugoon.com"
      }
    }
  }
}

A few things to note:

BUGOON_API_URL should be https://bugoon.com for the cloud-hosted version. If you're running Bugoon Local (the self-hosted OSS edition), point this at your local server, for example http://localhost:3100.
BUGOON_SECRET_KEY is the server-side secret from Settings, not the widget's public API key. Using the wrong one is the most common setup mistake — more on that in the troubleshooting section below.
Add .mcp.json to your .gitignore if it contains your actual secret key. Alternatively, many teams commit the file with a placeholder and rely on each developer to fill in their own key locally.

Step 2: Verify the Connection in Claude Code

Open Claude Code in the same project directory where you placed .mcp.json. Claude Code automatically discovers MCP servers defined in that file when it starts.

To confirm the server loaded correctly, ask Claude Code directly:

Which MCP tools do you have available?

You should see bugoon listed as a connected server with tools including list_bug_reports, get_bug_report, get_screenshot, update_bug_report_status, and get_project. If the server isn't listed, check the troubleshooting section at the end of this post.

You can also verify from the Claude Code sidebar: look for the MCP icon (a plug symbol) and expand it to see connected servers. A green indicator next to bugoon means the handshake succeeded and the server is ready to accept tool calls.

Step 3: Fetch Your First Bug Report

With the connection confirmed, try pulling a real bug report. In Claude Code, type:

Use the bugoon MCP to list the most recent bug reports for my project.

Claude Code will call list_bug_reports and return a summary of open reports — including the title, status, and when each was submitted. If your project has reports waiting, you'll see them here immediately.

To drill into a specific report, ask:

Get the details for bug report #42, including the screenshot.

This triggers get_bug_report followed by get_screenshot, giving Claude Code the full picture: the reporter's description, the URL where the bug occurred, any annotation data, and the actual screenshot. From here, Claude Code has everything it needs to propose a fix — without you copying and pasting a single thing.

You can also use the built-in prompts. Try:

Run the fix_bug prompt for bug report #42.

The fix_bug prompt bundles context retrieval and fix generation into a single guided workflow. The triage_bug prompt is useful when you want Claude Code to assess severity and suggest priority before committing to a fix.

Cursor Setup: One Extra File Location

The configuration for Cursor is identical in content — same JSON structure, same environment variables. The only difference is where the file lives.

Cursor reads MCP server config from .cursor/mcp.json (note the .cursor/ subdirectory, not the project root). Create that directory if it doesn't exist, then write the file:

.cursor/
  mcp.json       <-- Cursor reads from here

{
  "mcpServers": {
    "bugoon": {
      "command": "npx",
      "args": ["-y", "@rubyjobs-jp/bugoon-mcp-server"],
      "env": {
        "BUGOON_SECRET_KEY": "YOUR_SECRET_KEY",
        "BUGOON_API_URL": "https://bugoon.com"
      }
    }
  }
}

After saving the file, restart Cursor or reload the window (Cmd+Shift+P > Developer: Reload Window). Open the Cursor Settings panel, navigate to Features > MCP, and confirm bugoon appears with a green status badge. The tool list and behavior are identical to Claude Code from this point forward.

If you work in both editors, you can maintain both files in parallel — .mcp.json at the root for Claude Code and .cursor/mcp.json for Cursor — with the same contents.

Common Config Mistakes and How to Fix Them

Trailing comma in JSON

JSON does not allow trailing commas, but they're easy to introduce by accident:

{
  "mcpServers": {
    "bugoon": {
      ...
      "env": {
        "BUGOON_SECRET_KEY": "sk-...",
        "BUGOON_API_URL": "https://bugoon.com"
      }
    }
  }
}

The server will silently fail to load if the JSON is malformed. Run node -e "require('./mcp.json')" (or the path to your config file) to validate it before debugging anything else.

Key name typo

The environment variable names are case-sensitive and must match exactly:

BUGOON_SECRET_KEY — not BUGOON_API_SECRET, not SECRET_KEY, not BUGOON_secret_key
BUGOON_API_URL — not BUGOON_URL, not API_URL

If either variable name is wrong, the server starts but every tool call returns an authentication error. Double-check spelling first.

Using the widget API key instead of the Secret Key

Bugoon issues two different credentials per project. The API Key (a 64-character string beginning with your project identifier) is embedded in the JavaScript widget tag and is safe to expose publicly — it only allows submitting bug reports. The Secret Key is server-side only and grants read/write access to your bug reports through the MCP server.

If you paste the widget API key into BUGOON_SECRET_KEY, the MCP server will respond with a 401 Unauthorized error on every call. Go back to Dashboard > Settings > API Keys, copy the value labeled Secret Key, and replace the placeholder.

Editor not picking up the file

Claude Code requires .mcp.json to be in the directory you opened as your workspace root. If you opened a subdirectory (for example, just the frontend/ folder in a monorepo), the file won't be found. Open the repo root instead, or copy the config file into whichever directory the editor treats as root.

Next Steps: Let AI Fix Your Bugs

You now have a direct channel from your AI coding assistant to your live bug queue. Every report your users submit through the Bugoon widget is instantly accessible to Claude Code or Cursor — with full context, screenshots, and interaction history included.

The natural next step is to close the loop: have your AI assistant not just read the bug, but actually write the fix, open a pull request, and update the report status back to resolved — all from a single prompt. That workflow, including how to use the fix_bug prompt effectively and what context to provide for best results, is covered in the next post in this series.

Try Bugoon for free

5-Minute Setup: Connect Bugoon MCP Server to Claude Code or Cursor