GitHub Copilot - Beads Documentation

Beads gives Copilot a persistent, structured memory for tracking work: with the MCP server configured, you create, update, and track issues in natural language without leaving the editor. This page covers Copilot Chat in VS Code via MCP. For the terminal-based Copilot CLI plugin installed by bd setup copilot, see Copilot CLI.

Prerequisites

VS Code 1.96+ with the GitHub Copilot extension
A GitHub Copilot subscription (Individual, Business, or Enterprise)
The beads CLI installed (installation guide)
Python 3.10+ or the uv package manager

Setup

Quick Setup

Install beads-mcp:

# Using uv (recommended)
uv tool install beads-mcp

# Or using pip / pipx
pip install beads-mcp
pipx install beads-mcp

Create .vscode/mcp.json in your project:
```
{
  "servers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}
```
For all projects: Add to VS Code user-level MCP config:
Platform Path
macOS ~/Library/Application Support/Code/User/mcp.json
Linux ~/.config/Code/User/mcp.json
Windows %APPDATA%\Code\User\mcp.json
```
{
  "servers": {
    "beads": {
      "command": "beads-mcp",
      "args": []
    }
  }
}
```
Initialize beads:
```
bd init --quiet
```
This creates a .beads/ directory with the issue database.
Reload VS Code

Platform	Path
macOS	`~/Library/Application Support/Code/User/mcp.json`
Linux	`~/.config/Code/User/mcp.json`
Windows	`%APPDATA%\Code\User\mcp.json`

Verify Setup

Ask Copilot Chat: “What beads issues are ready to work on?”

Using Natural Language

With MCP configured, interact naturally:

You: Create a bug for the login timeout
Copilot: Created bd-42: Login timeout bug

You: What issues are ready?
Copilot: 3 issues ready: bd-42, bd-99, bd-17

You: Claim bd-42, I'll take it
Copilot: Claimed bd-42 and started work

You: I found a related bug - the session token isn't refreshed.
     File it, linked to bd-42.
Copilot: Created bd-103: Session token not refreshed
         Linked as discovered-from bd-42

You: Close bd-42 with reason "Fixed timeout handling"
Copilot: Closed bd-42: Fixed timeout handling

Syncing stays on the CLI: run bd dolt push at the end of a session. There is no MCP push tool.

MCP Tools

Tool	Description	You say
`ready`	List unblocked issues	”What can I work on?”
`list`	List issues with filters	”Show all open bugs”
`show`	Show issue details, including dependencies and dependents	”Show bd-42 details”
`create`	Create new issue	”Create a task for refactoring”
`claim`	Atomically claim an issue (assignee + in_progress)	“I’ll take bd-42”
`update`	Update issue fields	”Set bd-42 to priority 1”
`close`	Close an issue	”Complete bd-42”
`dep`	Add dependency	”bd-99 blocks bd-42”
`blocked`	Show blocked issues and their blockers	”What’s blocking my work?”
`stats`	Issue counts and average lead time	”How’s the backlog?”

The server also exposes reopen, comment, comments, note, context, and admin; call discover_tools for the full catalog.

Copilot Instructions

Optionally add .github/copilot-instructions.md:

## Issue Tracking

This project uses **bd (beads)** for issue tracking.
Run `bd prime` for workflow context.

Quick reference:
- `bd ready` - Find unblocked work
- `bd create "Title" --type task --priority 2` - Create issue
- `bd close <id>` - Complete work
- `bd dolt push` - Push changes to Dolt remote (run at session end)

CLI vs MCP

Approach	Best for	Trade-off
MCP (Copilot Chat)	Natural language, discovery	Higher token overhead
CLI (terminal)	Scripting, precision, speed	Requires shell access

Both work against the same database - use MCP for conversational work, the CLI for quick commands. See MCP Server for the full trade-off discussion.

Troubleshooting

Tools not appearing

Check VS Code 1.96+
Verify mcp.json syntax is valid JSON
Reload VS Code window
Check Output panel for MCP errors

”beads-mcp not found”

# Check installation
which beads-mcp
pip show beads-mcp

# uv installs to ~/.local/bin - make sure it's on PATH
export PATH="$HOME/.local/bin:$PATH"

# If installed with pip, find it
pip show beads-mcp | grep Location

# Reinstall if needed
uv tool install beads-mcp --force

No database found

bd init --quiet

Changes not persisting

Push to the Dolt remote at the end of your session, from the terminal:

bd dolt push

Organization policies blocking MCP

For Copilot Business/Enterprise, your organization must enable the “MCP servers in Copilot” policy. Contact your admin if MCP tools don’t appear despite a correct config.

FAQ

Do I need to clone beads?

No. Beads is a system-wide CLI tool. Install once, use everywhere. The .beads/ directory in your project only contains the issue database.

What about git hooks?

Git hooks are optional. They refresh exports and legacy fallback checks, while issue sync uses bd dolt push / bd dolt pull. They never modify your source code; skip them with bd init --skip-hooks.

Can I use beads without Copilot?

Yes. The same database works from the terminal, Claude Code, Cursor, Aider, and any editor with MCP or shell access.

Does this work with Copilot in other editors?

This page covers VS Code. For JetBrains IDEs, check whether your IDE supports MCP; the config location differs. For Neovim, use the CLI directly. For the terminal, see Copilot CLI.

​Prerequisites

​Setup

​Quick Setup

​Verify Setup

​Using Natural Language

​MCP Tools

​Copilot Instructions

​CLI vs MCP

​Troubleshooting

​Tools not appearing

​”beads-mcp not found”

​No database found

​Changes not persisting

​Organization policies blocking MCP

​FAQ

​Do I need to clone beads?

​What about git hooks?

​Can I use beads without Copilot?

​Does this work with Copilot in other editors?

​See Also