## 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](github.md) 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.