Shortcut stories

Connect a workspace

1. Open Settings → Connected sources → Shortcut.
2. Select Create a token in Shortcut.
3. In the correct Shortcut workspace, create a personal API token.
4. Paste the token into Plan Your Work. If areas are enabled, choose a Workspace area.
5. Select Connect Shortcut. The workspace and member appear with a Connected label.

If the connection fails, the form shows the reason. Correct the problem and enter the token again.

Use Add connection for each additional connection. Each connection identifies a Shortcut member and workspace. Organizations can have several workspaces. Connecting the same member and workspace again replaces its token without duplicating its stories. New tokens and older tokens are supported. The connector selects the API automatically. The token must allow story edits for two-way sync.

Tokens are encrypted when saved. Settings show a mask, never the saved token. To rotate a token, expand API token, enter a replacement for the same workspace and account, and save. Revoke the previous token in Shortcut after replacing it.

Find and organize stories

The first sync creates a project named after your workspace. It imports open, unarchived stories where you are an owner. Following, requesting, or commenting on a story alone does not import it. Completed history is not imported when you first connect.

With areas enabled, Workspace area defaults to Work when connecting. Choose another Workspace area in connection settings, or organize the project directly. You can rename, nest, or link the project. Sync preserves its local organization. Moving a story to another local project does not move it in Shortcut. Linking projects never copies stories between external sources.

Edit and complete stories

Shortcut stories show their current workflow state beside the project name. Open the task editor and select Shortcut state to use that story’s workflow. These controls appear only on imported Shortcut stories.

Field or action	Behavior
Task name	Updates the story name
Notes	Updates the story description, not a comment
Due date	Updates or clears the story deadline
Shortcut state	Updates the story’s workflow state
Complete	Selects the first Done state in workflow order
Reopen	Selects the first Unstarted state, then Backlog or Started if needed
Priority and Show from	Stay in Plan Your Work
Create or delete stories	Use Shortcut; new tasks here stay local

A Done state completes the task. Other states keep it active. Automatic task completion is unavailable for Shortcut stories. Owners, story type, estimates, labels, comments, and workflow definitions are managed in Shortcut. Ownership is checked again before sending an edit. Your token’s permissions apply.

Link pull requests to stories

When GitHub is connected too, a pull request that names a story shows that story and its workflow state, and the story shows its pull requests. A pull request names a story with sc-1234 in its title, branch, or description, or with the story’s URL, the same references Shortcut’s GitHub integration reads.

If your team expects every pull request to name a story, choose its GitHub accounts under Pull requests that name a story in the connection settings, then select Save settings. Your ready pull requests in those accounts that name no story show No ticket, and No ticket appears in the state filter. Drafts and dependency updates are left out. Nothing is chosen until you choose it.

Sync and disconnect

Connections check for changes every five minutes. Sync now requests an earlier refresh. Supported edits queue an update automatically. Failed updates retain the pending edit and show a connection error. Local pending edits survive a background refresh.

Imported stories complete locally when they reach Done in Shortcut. Reopened owned stories return to the active list on the next sync. Stories that you no longer own, archived stories, and unavailable stories leave the local list after sync. Pending edits are retained until resolved; an ownership change can prevent those edits from syncing. An incomplete or failed sync does not remove existing tasks.

Disconnect removes that connection’s credentials and imported stories from Plan Your Work. Local tasks and other connections remain. Stories in Shortcut stay unchanged. Revoke the token in Shortcut if you also want to invalidate it there.

Use with AI agents

MCP task results include external_state_id and available states in source_data.states. Call update_task with a state ID as a string to change a Shortcut story’s state. complete_task and reopen_task use the same state rules as the interface. Read this guide through get_documentation with slug: "shortcut". Tokens are never included in MCP task or project results.