# Shortcut MCP

> Shortcut MCP Server lets your AI agent act as a full project auditor right inside your IDE. Use it to search for specific stories, check every Epic on the roadmap, list all team members, or audit complex workflows without touching the web UI.

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

## Description

Your AI client doesn't have to click through endless boards just to get answers. This server gives your agent direct, administrative access to everything in your Shortcut project management environment, letting you treat it like a raw data source instead of a pretty dashboard. You can turn natural conversation into actionable API calls that pull the exact info you need.

Think of this setup as having a full-time auditor on retainer who knows every corner of your backlog and process flow. It lets you interrogate backlogs, audit sprints, and check team structure without ever opening the main web UI or touching a single button. You're working with the system’s underlying data layer.

When you need to find something specific, `search_stories` searches the entire backlog for stories using keywords or filters; it finds tickets across all projects that match what you’re looking for. If you zero in on one ticket and need every detail—the full description, sub-tasks, and history of changes—you use `get_story_details` to pull everything associated with a single ticket ID.

For tracking the big picture, you can audit your project roadmaps by running `list_epics` to get a list of all high-level Epics in your workspace. You'll also run `list_iterations` to see every active sprint or time-boxed cycle for the whole project. This lets you track roadmap status without having to open up the main dashboard and click through multiple tabs.

To map out who's running what, you can pull a list of all workspace members using `list_members`. You also use `list_projects` when you need to identify every distinct project that exists within your overall Shortcut account structure. This gives you a complete scope of the organization’s work.

If you wanna check how things actually flow, you run `list_workflows` to see every possible state and transition path an issue can take in your company. That's your blueprint for process auditing. You can also use `list_workflows` to understand every defined workflow and all the specific states a story might pass through.

This comprehensive set of tools means you don’t have to guess where data lives or spend time navigating menus. Your agent handles the heavy lifting, giving you clean, raw data sets instantly—whether that's checking the full scope of your project structure via `list_projects`, getting a snapshot of all active sprints with `list_iterations`, or locating one obscure ticket deep in the backlog using `search_stories`. It’s pure power for your agent to run these administrative checks and audits right where you write code.

## Tools

### get_story_details
Retrieves all necessary details for a single, specific story ticket.

### list_epics
Lists every high-level Epic in your Shortcut workspace.

### list_iterations
Lists all active sprints or time-boxed iterations for the project.

### list_members
Retrieves a list of every user member in your Shortcut workspace.

### list_projects
Lists all distinct projects within the overall Shortcut account structure.

### list_workflows
Shows every defined workflow and all possible states a story can transition through.

### search_stories
Searches the entire backlog for stories using keywords or filters.

## 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 for specific stories
Run `search_stories` to find tickets based on keywords or criteria across the entire backlog.

### Retrieve detailed story information
Use `get_story_details` to pull every description, sub-task, and piece of history for a single ticket ID.

### Audit project roadmaps
List all high-level Epics (`list_epics`) and ongoing sprints (`list_iterations`) to track roadmap status without opening the main dashboard.

### Map team structure
Pull a list of all workspace members using `list_members` or identify entire projects via `list_projects`.

### Inspect workflow states
Run `list_workflows` to see every possible state and transition path an issue can take in your organization.

## Use Cases

### Auditing a stalled roadmap
The PM realizes the Q3 goals are slipping. They prompt their agent: "List all Epics and then list all iterations." The agent runs `list_epics` followed by `list_iterations`, instantly showing which sprints haven't been updated in weeks, allowing them to flag bottlenecks immediately.

### Checking team roles before a meeting
A developer needs to know who owns the 'Billing' project. They prompt: "Show me all projects and then list members for Project X." The agent first calls `list_projects` to find the ID, then uses `list_members` to deliver a precise roster of required stakeholders.

### Debugging an unknown task state
A QA tester finds a story stuck in 'Pending Review.' They prompt: "What are all possible workflows for this project?" The agent runs `list_workflows`, showing the exact states and transitions, proving if the current status is even valid.

### Mass incident review
The team needs to check every story referencing 'login failure' from last month. They run a focused prompt: "Search stories for login failures." The agent executes `search_stories`, returning all relevant ticket IDs, which they can then use with `get_story_details` for deep context.

## Benefits

- Stop clicking through dashboards. You can interrogate task backlogs and audit sprints using `list_epics` or `list_iterations` directly via natural prompts.
- Need deep context on one ticket? Use `get_story_details`. It pulls every sub-task, description, and detail for a story without leaving your IDE.
- Verify team structure instantly. Run `list_members` to get all user IDs or use `list_projects` to see the full scope of work happening across different containers.
- Understand task flow immediately. Checking `list_workflows` shows you every possible state and transition a story can hit, which is critical for identifying process blockers.
- Pinpoint issues fast. Instead of manual filtering, use `search_stories` to find all tickets mentioning 'database timeout' across the whole backlog.

## How It Works

The bottom line is, you send a natural language prompt, and the server executes multiple API calls using the appropriate tool.

1. Anchor this core interface directly into your AI agent framework.
2. Securely store your `SHORTCUT_API_TOKEN` within the workspace boundary. This locks down security.
3. Prompt your agent: "Find all bugs reported this week and tell me what Epic they belong to based on their details!"

## Frequently Asked Questions

**How do I find a specific story using search_stories?**
Just ask your agent to run `search_stories` with keywords. You can specify 'database timeout' or 'login failure,' and it hits the entire backlog.

**What is list_epics used for?**
`list_epics` lists all major Epics in your workspace. This lets you see the top-level goals—the big roadmap items—without needing to filter through thousands of individual stories.

**Can I use get_story_details on a specific ticket?**
Yes, that's its job. You pass it the story ID, and it pulls every piece of associated data for you: all sub-tasks, notes, descriptions, etc.

**What is the difference between list_projects and list_members?**
`list_projects` gives you a directory of work containers. `list_members` tells you which people exist in the system; they are separate lists used for different types of context.

**How should I authenticate my connection to use `list_workflows` securely?**
You must provide a dedicated API token within your agent's environment. This token controls the scope of access, ensuring your AI client can only read project data you explicitly authorize.

**How does using `list_workflows` help map all possible issue states?**
It lists every defined workflow and its associated status tags. This reveals exactly which statuses (e.g., 'To Do' or 'In Review') a story can legally transition into within the Shortcut system.

**When running deep searches with `search_stories`, what should I expect if the API hits a rate limit?**
The server handles standard API rate limiting through structured error responses. Your agent must implement retry logic, specifically checking for HTTP 429 status codes to manage flow interruptions gracefully.

**Does `list_iterations` handle large datasets by allowing pagination?**
Yes, the tool supports cursor-based pagination. When a request exceeds the default page size, subsequent calls must use the provided next cursor token to retrieve all remaining data chunks.

**Can the integration alter, comment in, or edit stories directly?**
By structural design, this module is strictly bound as an observational lens. Operations such as `search_stories`, `list_epics`, and `get_story_details` parse and extract massive context. It omits explicitly write mechanisms preventing your autonomous agent from accidentally sabotaging valid roadmap components permanently.

**Why use the token via MCP instead of normal webhook integrations?**
Webhooks exclusively wait for explicit platform triggers passively. The MCP configuration hands your prompt active, unadulterated runtime authority to scan iterations, grab user arrays, and interrogate backlog metadata aggressively instantly dynamically. It permits pulling, rather than simply listening blindly.

**Can the integration directly access workspaces not associated with the token creator?**
No. The highly sensitive REST API access token acts inherently as a mapped functional clone of the exact user credentials operating at generation time. Searching workflows, epics, and members evaluates precisely against the internal permissions bounds of the token creator robustly limiting toxic footprint.