MCP Workflow

Backlog.md integrates deeply with AI coding assistants through the Model Context Protocol (MCP). MCP is a standardized protocol that allows AI agents to directly invoke Backlog.md's functional tools without users manually typing CLI commands. With MCP, AI can read, create, and manage tasks like a human developer, enabling true collaborative project management.

What Is MCP Integration

In the traditional approach, AI assistants could only learn Backlog.md's CLI commands from instruction files and then execute shell commands on their own. This had two problems:

• AI had to parse shell output, which was error-prone.
• When command execution failed, AI had difficulty accurately determining the cause.

MCP integration fundamentally changes this model. AI agents call Backlog.md's tool functions directly through a standardized protocol, with structured parameters and return values, greatly improving reliability. The Backlog.md MCP server runs locally and communicates with AI clients via stdio, exposing no network ports.

Spec-Driven Workflow

A Spec-Driven workflow is recommended for collaborating with AI: break large requirements into small tasks and implement them step by step. The process is divided into four steps.

Step 1: Describe the Idea

Describe the feature you want to build or the problem you want to solve to the AI agent. The AI will help you break the idea into multiple small tasks, each with a clear description and acceptance criteria. Tasks should be small enough to be completed in a single conversation.

Example conversation:

I want to add user authentication to the project. Please break it into executable tasks, each with acceptance criteria.

Step 2: One Task at a Time, One Task per PR

Each agent session handles only one task. This constraint offers three benefits:

• More focused context and better AI understanding.
• Each task corresponds to an independent Pull Request, making code review easier.
• If something fails, only a single task needs to be redone, without affecting a large amount of code.

Before starting a new task, have the AI read the current task details:

backlog task <id> --plain

Step 3: Write the Implementation Plan Before Coding

Before implementing code, have the AI study the current codebase, then write an Implementation Plan and write it into the task via CLI:

backlog task edit <id> --plan "1. Study existing code structure
2. Design interfaces
3. Implement core logic
4. Add tests"

The implementation plan ensures the proposal reflects the current state of the codebase and prevents AI from developing based on outdated assumptions. After writing the plan, it is recommended to confirm with team members before starting coding.

Step 4: Implement and Verify

The AI agent writes code according to the implementation plan. After completion, perform the following verification steps:

• Review AI-generated code to confirm it follows project standards.
• Run the test suite to ensure no existing functionality is broken.
• Run lint checks to keep code style consistent.
• Check acceptance criteria item by item to confirm they are all satisfied.
• Update the task status to Done.

backlog task edit <id> --check-ac 1 --check-ac 2 --check-ac 3
backlog task edit <id> -s Done

Restart Loop When Unsatisfied

If the AI's implementation does not meet expectations, do not keep spinning in the same session. The correct approach is:

1. Clear the old plan, notes, and final summary in the task.
2. Refine the task description and acceptance criteria based on lessons learned.
3. Start a new AI session and rerun the entire process.

The restart loop avoids context pollution and lets the AI re-examine the requirement with a clearer perspective.

MCP Tool Capability List

After connecting via MCP, the AI agent can call 33 tools, categorized by domain as follows (required parameters are marked (required)).

Tasks (7)

Documents (5)

Milestones (5)

Memos (5)

Memo tools share the same ID scheme (YYYYMMDD-N) and file format with the CLI and Web. See Memos for details.

Decisions (2)

Definition of Done (2)

Workflow (1)

Graph (6)

Tools for querying the task relationship graph and managing user databases. Graph tools use a one-shot switch model: each call goes through the full open → query → close cycle (default derived graph reuses snapshots already written by the Web UI GraphService), without keeping a GraphService resident in the MCP process, so it does not rebuild the corpus at startup or slow down MCP server startup.

The accompanying graph guide volume (backlog instructions graph / backlog://workflow/graph) covers parameters for the six tools and Cypher / CSV usage.

List Paging

All MCP list tools uniformly support offset + limit paging, returning structured results through a unified envelope:

{ "items": [], "total": 128, "offset": 0, "limit": 50, "hasMore": true }

• task_list, task_search, document_search, document_list, milestone_list, memo_list, and decision_list all follow this envelope; text output additionally appends a CLI-style Showing X-Y of N items hint.
• hasMore / total let the agent determine whether the list is complete and loop through pages accordingly—no more silent truncation.
• task_list pages by the ordered sequence of status buckets and then re-renders by bucket; bucket order is unchanged. The unconfigured / archived diagnostic sections of milestone_list are excluded from paging, ensuring warnings are not lost.

MCP Resources and Prompts

The Backlog.md MCP server registers the following workflow resources with the client; AI agents can actively read them during a session:

AI agents read backlog://workflow/overview first when connecting or encountering uncertain scenarios to get contextual guidance. The CLI-side backlog instructions <volume> corresponds one-to-one with the above volumes; see Agent Instruction Files.

Security Features

Backlog.md's MCP implementation is secure by design:

• stdio-only transport: AI clients and the MCP server communicate only through standard input/output, do not listen on any network port, and cannot be accessed externally.
• localhost-only runtime validation: Web UI and other services bind to local addresses by default.
• Pure protocol wrapper: the MCP layer contains no business logic; all operations are ultimately handled by the Core layer, sharing the same data validation rules as the CLI and Web UI.
• Roots discovery mechanism: the MCP client sends a list of workspace root directories, and Backlog.md automatically looks for valid projects in those directories. The normal startup path also follows changes in client workspace roots; when none is found, it falls back to a minimal-functionality mode exposing only init-related tools.
• Fixed project root: to lock to a fixed directory (for example global ~/.backlog), start with --cwd or the BACKLOG_CWD environment variable; the server will then not follow client workspace roots.

Frequently Asked Questions

Codex cannot connect to the Backlog.md MCP server

• Symptom: Codex reports MCP server startup failure or timeout.
• Common cause: the local backlog command resolves to a stale/corrupted dist/backlog binary.
• Solution:
  1. Rebuild the project (bun run build).
  2. Use the current Codex command format: codex mcp add backlog -- backlog mcp start.
  3. Test backlog mcp start separately to confirm it starts normally.

Shared MCP server writes to the wrong project

• Symptom: in user-level or shared-server scenarios, tasks created by AI appear in the wrong directory.
• Cause: older server versions parsed the project root only once at startup.
• Solution: upgrade to the latest version; to fix the directory, use backlog mcp start --cwd <path>.