Agile Backlog

You set up Agile MCP to manage agile backlog items across projects using a dedicated MCP server, with a human-friendly Web UI and a secure, isolated data store. This server lets AI agents and human teams collaborate on epics, stories, and tasks while tracking sprints, dependencies, and burndown analytics in a single, auditable system.

How to use

You interact with two primary interfaces. The MCP server exposes backlog-management capabilities to AI agents, while the Web UI provides a human-facing dashboard for creating and organizing epics, stories, and tasks. You can register projects, create backlogs, plan sprints, visualize dependencies, and monitor progress with burndown charts and velocity reports. When working with agents, you register a project, then create epics, stories, and dependencies as part of your collaborative workflow. The Web UI lets you manage everything visually, drag items on aKanban board, and inspect relationships in a dependency graph and hierarchy tree.

Practical usage patterns you can follow:

• Register a new project and switch between projects easily.
• Create epics to represent major feature areas, then add stories and tasks under each epic.
• Plan sprints, assign stories to sprints, and track capacity and velocity over time.
• Use the dependency graph to identify blocking relationships and prevent circular dependencies.
• Monitor progress with burndown charts and keep an auditable record of access and changes.

How to install

Prerequisites you need before starting:
- Node.js 18+
- npm 9+
- A modern browser for the Web UI (or a device capable of running a UI via http://localhost:3004)

Step-by-step setup:
- Ensure you have Node.js and npm installed on your machine.
- Install dependencies for all workspaces.
- Build the shared package.
- Build the MCP server.

Project isolation and security

Each project is uniquely identified and isolated, ensuring AI agents can access only items within their registered project. All access attempts are logged to support compliance auditing, and the system enforces cross-project access restrictions to protect data.

MCP server usage with an MCP client

To connect an MCP client to the server, you register your project with the MCP server and perform backlog operations through the available tool interfaces. The server supports epic, story, and task CRUD, sprint planning, burndown data collection, dependency management with circular-dependency prevention, and export capabilities. You can also view read-only MCP resources for backlog overviews and dependencies.

Web UI usage

Open http://localhost:3004 to access the human interface. Use the project selector to switch between projects or create a new one. The main features include creating, editing, and deleting epics, stories, and tasks; sprint creation and management; a Kanban-style sprint board with drag-and-drop; burndown charts; velocity reports; a backlog list with filtering; a dependency graph; and a hierarchy tree showing Epic → Story → Task relationships. The UI is designed to be mobile-friendly and responsive.

Core concepts

Projects isolate backlog data by unique identifiers, ensuring separate backlogs per repository. Epics, stories, and tasks form the backbone of the backlog. Sprints enable time-boxed work periods with capacity tracking, velocity metrics, and daily progress snapshots. Dependencies model story-to-story relationships and are visualized in an interactive graph to prevent blocking conditions. The standard workflow moves items through: todo → in_progress → review → done, with a path for blocked items.

Security and auditing

Security features include project isolation, access validation on all tools, and an audit trail for unauthorized attempts. Security events are categorized and accessible through the security logs endpoint for review and compliance.

Development and build

You can build and run the project locally with common npm commands. This setup emphasizes a clean, modular structure with a dedicated MCP server, a React-based Web UI, and a shared SQLite database.

Example workflows

AI Agent workflow examples include registering a project, creating an epic, adding a story, and establishing dependencies. Web UI workflow steps guide you through opening the UI, selecting or creating a project, creating epics and stories, creating a sprint, assigning stories to sprints, and exploring the dependency graph and hierarchy tree.

Notes and troubleshooting

If you encounter issues, verify your project is registered and that you are operating within the correct project scope. Check access controls and review the security audit logs for unauthorized access attempts. Ensure the server and UI are running and that the Web UI API endpoints are reachable from your browser.

Examples and reference configurations

The following configuration example shows how to connect an MCP client to the Agile MCP server from an agent (such as Claude) by referencing the local server entry point. This config uses a local stdio connection to the MCP server entry script.

Available tools

register_project

Register a new project with a unique identifier and metadata so AI agents and humans can interact with the backlog within an isolated project scope.

create_epic

Create a new epic under a specified project, including title and description to group related stories.

create_story

Create a story under a given epic, including priority, points, and status to plan work.

add_dependency

Define a dependency between stories (blocks/blocked_by) and automatically prevent circular dependencies.

update_item

Update epics, stories, or tasks to reflect progress, priority changes, or re-assignment.

delete_item

Remove epics, stories, or tasks while maintaining data integrity through cascade behavior.

export_backlog

Export backlog data for external analysis or reporting.

read_only_view

Provide read-only backlogs overview and dependencies for MCP clients.