# Shortcut MCP

> Shortcut MCP lets your AI agent run as an autonomous project auditor for your entire product backlog. Instead of clicking through endless boards, you can interrogate tasks, audit team assignments, and track high-level roadmaps—all by talking to your agent.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** issue-tracking, kanban, scrum-management, software-development, workflow-automation, epic-tracking

## Description

This connector gives your AI client total administrative control over your Shortcut development environment. It turns the tool into a dedicated project auditor that understands how your work flows across projects and sprints. Forget manually clicking through tabs or exporting data just to figure out where things stand. You can now ask natural questions—like, “Find all bugs reported this week and tell me what Epic they belong to.” The system pulls everything together for you, querying deep backlogs, mapping team structures, and auditing workflow states without ever opening a single tab. It's like having an instant scrum master sitting on your shoulder. Because Vinkius hosts this MCP, you connect once from any compatible client—Claude, Cursor, or Windsurf—and gain access to the entire suite of project management tools.

## Tools

### search_stories
Searches across the entire system to find any stories or tickets matching your keywords or criteria.

### get_story_details
Retrieves all nested details, sub-tasks, and full descriptions for a specific story ID.

### list_epics
Provides an overview of every major initiative or large project grouping (Epic) in the workspace.

### list_iterations
Lists all defined development cycles, commonly known as sprints, to track timeline progress.

### list_projects
Gives you a categorized list of every active project within the organization's portfolio.

### list_workflows
Lists all custom state pipelines and workflows, showing exactly how issues can move through your process.

### list_members
Retrieves a directory of every user account assigned to the Shortcut workspace.

## Prompt Examples

**Prompt:** 
```
Find all stories mentioning 'database timeout' using keyword search.
```

**Response:** 
```
Executing `search_stories` aggressively with query terms `"database timeout"`. Found 3 latent incident logs heavily referencing database connection anomalies tied predominantly to the recent infrastructure rollout. Would you like me to deeply retrieve their nested tasks exploiting `get_story_details` sequentially?
```

**Prompt:** 
```
List all ongoing epics and let me evaluate our current roadmap vectors.
```

**Response:** 
```
Triggering the macro-level aggregator `list_epics`. Discovered 8 massive roadmap clusters actively in motion. Noteworthy dense collections prominently included "Q3 Payment Refactor" housing severely delayed workflow statuses and "Client App Redesign" exhibiting strong momentum matrices safely. Should I drill downwards targeting specific iterations next?
```

**Prompt:** 
```
List workflows to show me all valid issue states in this organization.
```

**Response:** 
```
Initiating standard extraction accessing `list_workflows` exclusively. Successfully isolated 2 primary organizational workflow state pipelines. 'Engineering Workflow' notably incorporates active transition tags directly translating as 'Unstarted', 'Ready for Dev', 'In Development', securely mapping seamlessly into endpoint resolution state uniquely marked 'Completed'.
```

## Capabilities

### Search Project Stories
Searches through your entire backlog to find specific tasks or features using keywords.

### Get Story Details
Retrieves every piece of information, including nested sub-tasks and descriptions, for a single story.

### Audit Project Roadmaps
Lists all major project clusters (Epics) to give you a high-level view of the entire roadmap.

### Track Development Sprints
Lists current and past sprints (Iterations) so you can monitor development momentum.

### Map Project Structure
Retrieves a list of all active projects within the organization's workspace.

### Analyze Workflow States
Lists every custom workflow and its valid states to understand how tasks move through your pipeline.

## Use Cases

### Forecasting Release Readiness
A PM needs to know if the upcoming release is on track. They prompt their agent: 'List all epics related to payments, then list iterations for those that show a status of less than 80% complete.' The agent runs list_epics and list_iterations, giving them an immediate risk assessment.

### Auditing Process Gaps
A team lead questions why some tickets are stuck. They ask the agent to run list_workflows. Seeing the available states, they realize a crucial 'Legal Review' stage is missing from their process flow.

### Investigating Technical Debt
A developer needs historical context on an old bug fix. They prompt for stories mentioning 'database timeout'. The agent uses search_stories and then calls get_story_details on the top three results, providing immediate architectural insight.

### Onboarding New Team Members
A new PM needs to know who handles what. They prompt the agent to list all projects and list members. The agent maps the organizational chart and assigns ownership for key areas.

## Benefits

- Stop navigating through dozens of boards. By listing all epics and calling list_iterations, you get a single view of the whole roadmap's scope, letting you see potential bottlenecks immediately.
- You eliminate manual data gathering. Need to know exactly what was worked on? Use search_stories first, then use get_story_details to extract every sub-task without clicking through the UI.
- Understand your team structure instantly. list_members lets you check who is on the board, and list_projects tells you where they fit into the overall organizational portfolio.
- Get clarity on process compliance. Calling list_workflows shows all valid states—like 'Ready for Dev' or 'In Development'—so you know exactly what steps a story must take to be finished.
- Run complex queries in natural language. Instead of writing complicated filters, just ask your agent to find specific types of tasks using search_stories and get the results instantly.

## How It Works

The bottom line is you get administrative control over your entire product backlog without leaving your IDE.

1. First, you anchor this MCP within your agent's framework and securely provide the necessary API token.
2. Next, you instruct your agent using plain language prompts—for example, asking it to find all tasks related to 'database timeout'.
3. The agent executes multiple tools behind the scenes, compiling raw project data into a single, readable answer directly in your chat window.

## Frequently Asked Questions

**How does search_stories work with other tools in the Shortcut MCP?**
search_stories finds a ticket ID first, which you can then pass to get_story_details. This lets your agent retrieve deep data on a specific story after finding it via keywords.

**Can I use list_workflows to see the status of my current project?**
list_workflows shows all possible states in the entire organization, but you still need to run search_stories or get_story_details on a specific ticket to see its *actual* current state.

**What if I want to know who works on a certain Epic?**
You first use list_epics to find the epic name, and then you ask your agent to cross-reference that data with list_members. It's an automated lookup.

**Is this MCP better than just using Shortcut’s native search?**
Yes, because it doesn't just search; it aggregates and interprets the results. Your agent runs multiple tools (like list_epics and list_iterations) simultaneously to give context you can't get from a single view.