Skip to content

Bug tracking for AI coding agents with MCP

A coding agent finds bugs while it works and reads your backlog to decide what to do. Over MCP it can do both in your tracker, with a key that only reaches the project you chose.

Written by the BugBoard team. 6 minute read. Updated 16 November 2026.

What MCP is

MCP, the Model Context Protocol, is an open standard for connecting AI applications to outside systems. An MCP server lists the tools it offers, such as “search tasks” or “create task”, and an agent that supports MCP can call them. Claude Code and Cursor both document how to connect to a remote MCP server with an authorization header. You add the server once, and the agent sees the tools.

Set it up

  1. In BugBoard, open the MCP page and create a key (or use OAuth sign-in if your client supports it, described below). A key starts with bb_ and is shown once, so copy it straight into an environment variable named BUGBOARD_MCP_TOKEN. By default a key is valid for 90 days.
  2. Add the server to the agent. The endpoint is https://api.bugboard.ai/mcp/sse. For Claude Code, run the command below, or put the same settings in .mcp.json in your repository.
  3. Keep the key out of the file. The config reads it from the environment variable, so the file is safe to commit.
  4. Ask the agent to list your projects. If it answers, the connection works.
claude mcp add --transport http bugboard https://api.bugboard.ai/mcp/sse \
  --header "Authorization: Bearer $BUGBOARD_MCP_TOKEN"

Cursor reads .cursor/mcp.json with the same URL and the header Authorization: Bearer ${env:BUGBOARD_MCP_TOKEN}. The page for each client, such as /mcp-server/claude-code and /mcp-server/cursor, has the exact file for it.

Give each agent the least access it needs

A key can be narrowed below the access of the person who owns it. It can carry scopes, project.read and project.write being the two an agent usually needs, and it can be limited to named projects. A key with only project.read is refused on anything that changes data. A key limited to one project cannot see the others at all: they are missing from project lists and from search, not just locked. Scopes only ever remove access, never add it.

  • A triage agent that only reads and comments: project.read and project.write, one project.
  • A reporting agent that summarises the backlog: project.read, one project.
  • Do not give an agent org.manage. Nothing in a bug workflow needs it.
  • Where to set them: a key made on the MCP page has a name and your own access. When a client connects with OAuth sign-in instead of a pasted key, the consent screen asks which permissions and which projects to allow. A script can also create a narrowed key through the token endpoint (POST /api/v1/auth/token, with scopes and projectIds), listed in the API reference at /docs/api.
  • One key per agent or per job, so you can revoke one without stopping the rest. Each key is also rate limited, to 300 requests a minute by default.

What to put in CLAUDE.md or AGENTS.md

The agent will use the tools if they help, but it needs to be told when. Put a short block in CLAUDE.md, AGENTS.md or your client’s rules file. The site has a generator at /agents that writes one for your client. This is the shape it should have.

## Tracking bugs in BugBoard (MCP server "bugboard")

- Project: <project id and name>. Use only this project.
- Before filing anything, run check_duplicates with the title
  you plan to use. Then run search_tasks with two or three
  keywords from the report.
- If a match exists, comment on it with what you found.
  Do not create a second task.
- File a bug only when you have reproduced it or have a failing
  test or log. Use type "bug".
- Fill in the seven fields below. Leave a field out only when
  you do not know it, and say so.
- Never close or delete a task. Never change a priority a
  person set.
- Do not put secrets, tokens or customer data in a task.

Rules for an agent that files bugs

The seven fields from the bug report guide apply to an agent as much as to a person: title, environment, steps to reproduce, expected result, actual result, evidence and impact. Agents tend to fail in three ways, and each has a fix.

  • Duplicates. An agent that sees the same failing test twice files twice. check_duplicates takes the project, the type and the candidate title, and returns near-exact title matches. It does not understand meaning, so also run search_tasks, which looks for your words in titles and descriptions.
  • Vague titles. Tell the agent to name what is wrong and where, in one line, as a person would.
  • Guessing. A report that states a guessed cause as fact sends the next person the wrong way. Ask the agent to label guesses as guesses.

What this does not do

MCP gives the agent access to your tasks. It does not make the agent good at judging them. A person should still read what it files, at least in the first weeks. Review the tasks it creates once a day, and tighten the CLAUDE.md block where it went wrong. A key that is lost or leaked should be re-issued at once, which cancels the old one.

A first session to try

  1. Create a project called “Agent sandbox” and a read and write key limited to it.
  2. Ask the agent to review a small part of your code and file what it finds.
  3. Check that each task has the seven fields and that none is a duplicate.
  4. Fix the rules, then point the agent at the real project.