MCP Workflow Tutorial — AI-Assisted Project Management

This tutorial walks through a realistic project management workflow using Alloy’s MCP tools with an AI assistant. Each section shows the natural-language prompt you give, the tool the assistant calls, the parameters it sends, and the result you see — so you can follow along in Claude Desktop or Claude Code.

Prerequisites: Alloy is running with the demo seed data loaded (./scripts/seed-demo.sh). The MCP server is connected to your AI assistant (see MCP Guide). The demo data creates an Acme Corp organization with a DEMO project, 6 tickets, a sprint, comments, and time entries.

1. Verify Connectivity

Before doing any real work, confirm the MCP connection is live.

Prompt:

Check my Alloy connection

Tool called: ping

Parameters: (none)

Result:

Alloy MCP connected to http://localhost:3000 as demo@alloy.dev (org acme-corp)

2. Check Your Identity

See who you are authenticated as and which organization you belong to.

Prompt:

Who am I in Alloy?

Tool called: whoami

Parameters: (none)

Result:

{
  "user_id": "b2f0c4e8-...",
  "org_id": "a1e0d3f7-...",
  "email": "demo@alloy.dev",
  "role": "Admin"
}

3. Get the Project Summary

Get a high-level view of the DEMO project — ticket counts by status and active sprints.

Prompt:

Give me a summary of the DEMO project

Tool called: get_project_summary

Parameters:

Result:

{
  "project": {
    "id": "c3a1b5d9-...",
    "name": "Demo Project",
    "key": "DEMO",
    "description": "A demo project for Alloy"
  },
  "ticket_summary": {
    "total": 6,
    "by_status": {
      "Backlog": 3,
      "InProgress": 2,
      "Done": 1
    },
    "has_more": false
  },
  "sprints": [
    {
      "id": "d4b2c6ea-...",
      "name": "Sprint 1",
      "status": "Active",
      "start_date": "2026-03-28",
      "end_date": "2026-04-11"
    }
  ]
}

The project has 6 tickets: 3 in Backlog, 2 in progress, and 1 done. Sprint 1 is active.

4. Search for High-Priority Tickets

Find all high-priority tickets to decide what to work on next.

Prompt:

Show me all High priority tickets in the DEMO project

Tool called: search_tickets

Parameters:

Result:

{
  "data": [
    {
      "id": "e5c3d7fb-...",
      "ticket_number": 1,
      "title": "Set up CI pipeline",
      "status": "Backlog",
      "priority": "High",
      "assignee_id": null
    },
    {
      "id": "f6d4e80c-...",
      "ticket_number": 2,
      "title": "Fix login redirect",
      "status": "InProgress",
      "priority": "High",
      "assignee_id": null
    },
    {
      "id": "a7e5f91d-...",
      "ticket_number": 6,
      "title": "Deploy staging",
      "status": "Backlog",
      "priority": "High",
      "assignee_id": null
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Three high-priority tickets. “Fix login redirect” is already in progress; “Set up CI pipeline” and “Deploy staging” are still in the backlog.

5. Assign a Ticket to Yourself

Pick up “Set up CI pipeline” by assigning it to yourself.

Prompt:

Assign the “Set up CI pipeline” ticket to me

Tool called: assign_ticket

Parameters:

Result:

{
  "id": "e5c3d7fb-...",
  "ticket_number": 1,
  "title": "Set up CI pipeline",
  "assignee_id": "b2f0c4e8-...",
  "updated_at": "2026-03-29T10:05:00Z"
}

The ticket is now assigned to you.

6. Transition a Ticket Through the Workflow

Move “Set up CI pipeline” from Backlog to Todo to start planning the work.

Prompt:

Move “Set up CI pipeline” to Todo

Tool called: transition_ticket

Parameters:

Result:

{
  "id": "e5c3d7fb-...",
  "status": "Todo",
  "updated_at": "2026-03-29T10:10:00Z"
}

Now try an invalid transition — skip straight from Todo to Done:

Prompt:

Move “Set up CI pipeline” to Done

Tool called: transition_ticket

Parameters:

Result (error):

Transition failed: Cannot transition from Todo to Done. Current status: Todo. Available transitions: [InProgress, Cancelled]

The workflow enforces valid transitions. From Todo, you can only move to InProgress or Cancelled. This prevents tickets from skipping review stages.

7. Add a Comment to a Ticket

Leave a note on the ticket with your implementation plan.

Prompt:

Add a comment to “Set up CI pipeline” saying “Will use GitHub Actions with Rust caching. ETA: end of sprint.”

Tool called: add_comment

Parameters:

Result:

{
  "id": "b8f6a02e-...",
  "ticket_id": "e5c3d7fb-...",
  "author_id": "b2f0c4e8-...",
  "body": "Will use GitHub Actions with Rust caching. ETA: end of sprint.",
  "parent_comment_id": null,
  "created_at": "2026-03-29T10:15:00Z"
}

8. Log Time on a Ticket

After working on the CI setup, log the time you spent.

Prompt:

Log 2 hours of Coding on “Set up CI pipeline” for today

Tool called: log_time

Parameters:

Result:

{
  "id": "c9a7b13f-...",
  "user_id": "b2f0c4e8-...",
  "ticket_id": "e5c3d7fb-...",
  "project_id": "c3a1b5d9-...",
  "date": "2026-03-29",
  "duration_minutes": 120,
  "activity_type": "Coding",
  "description": null,
  "status": "Draft",
  "created_at": "2026-03-29T12:15:00Z"
}

The time entry starts in Draft status. It can later be submitted for approval.

9. Create a New Ticket

While working on CI, you discover a blocker. Create a ticket for it.

Prompt:

Create a ticket in the DEMO project titled “Fix Docker build cache invalidation” with priority Urgent and description “Docker layer caching breaks on dependency updates, causing 20-minute builds”

Tool called: create_ticket

Parameters:

Result:

{
  "id": "d0b8c24a-...",
  "ticket_number": 7,
  "project_id": "c3a1b5d9-...",
  "title": "Fix Docker build cache invalidation",
  "description": "Docker layer caching breaks on dependency updates, causing 20-minute builds",
  "status": "Backlog",
  "priority": "Urgent",
  "assignee_id": null,
  "reporter_id": "b2f0c4e8-...",
  "created_at": "2026-03-29T12:20:00Z",
  "updated_at": "2026-03-29T12:20:00Z"
}

The new ticket is DEMO-7, automatically placed in Backlog.

10. Review the Sprint Burndown

End the session by checking how the sprint is tracking.

Prompt:

Show me the burndown chart for Sprint 1

Tool called: get_sprint_burndown

Parameters:

Result:

{
  "sprint_id": "d4b2c6ea-...",
  "data_points": [
    { "date": "2026-03-28", "total": 6, "completed": 1, "remaining": 5 },
    { "date": "2026-03-29", "total": 6, "completed": 1, "remaining": 5 }
  ]
}

Sprint 1 has 6 tickets with 1 completed so far. The burndown shows daily progress toward completing all sprint work by the end date (2026-04-11).

Summary

This workflow covered 10 of Alloy’s 49 MCP tools:

The remaining 39 tools — including project CRUD (create_project, list_projects, get_project, update_project, delete_project), label management (create_label, list_labels, add_ticket_label, remove_ticket_label), tag management (set_tags, get_tags, delete_tag, search_by_tag), sprint lifecycle (create_sprint, list_sprints, update_sprint, start_sprint, complete_sprint), workflow management (create_workflow, list_workflows, update_workflow), organization & access control (list_members, create_invite, list_invites, add_project_member, remove_project_member, list_project_members, create_api_key, list_api_keys, delete_api_key), activity (get_ticket_activity), and finance (get_time_report, get_capitalization_report, submit_time_entry, approve_time_entry) — are covered in the MCP Tools Reference.

For API-level details and curl equivalents, see the End-to-End Walkthrough.