This page is an agent-readable workflow for Deck. Humans can follow along. Coding agents should treat the steps as the source of truth.

Import Jira epics — agent workflow

• Use it when: the user says "import our Jira epics", "bring the Jira roadmap into Deck" or "add our epics to Deck".
• Outcome: the Jira epics that the user picked are Deck Projects, each linked to its epic. Nothing changes in Jira.
• Needs: Deck MCP and Jira connected to Deck. Only organization admins connect integrations, in Settings → Integrations. Any member can import an epic. Imports spend no credits.

1. Probe Deck MCP

Call get_user_context. This must be a real tool call.

• 401 Unauthorized: tell the user to connect Deck MCP in this client (Settings → Connections). Stop.
• No Deck tools: fetch and follow https://docs.getdeck.io/docs/agents/getting-started/prompts/ai-pm.md. Stop this workflow until the tools work.

2. Check the Jira connection

Call explore_integrations with integration_type: "JIRA". Read the state.

If the state is not_connected or needs_attention, tell the user that an organization admin must connect or reconnect Jira in Settings → Integrations. Give them the link from the result. Stop until Jira is connected.

3. Set the scope

Ask the user which epics to look at. Typical answers are one Jira project key, a text search, or all epics.

Deck uses Jira projects as containers for epics. A Deck Project links to one Jira epic, not to a Jira project.

4. List the epics

Call list_projects with importable_from: "jira" and kind: "epic".

• Add project_key for one Jira project.
• Add query for a Jira text search of epics.
• Set limit to 50 or less. When page_info.has_more is true, call again with cursor set to page_info.next_cursor.
• Do not add the Deck Project filters, such as status or owner. Deck returns VALIDATION_ERROR for them.

A row with already_linked_project_id is already in Deck. Its deck_url opens it. Do not import it again.

If the result has status: "not_connected", go back to step 2.

5. Find Deck Projects that already cover an epic

Call list_projects with no importable_from. Compare titles with the epic rows. When a Deck Project already covers an epic that is not linked, propose a link instead of an import. A link keeps the Deck Project and avoids a duplicate.

6. Show the plan and get a yes

Show one table: epic key, title, status, owner, and "already in Deck", "link" or "import". Ask the user:

• Which epics to import.
• Which segments to apply. Call explore_segments for the segment IDs.
• Which Deck initiative each epic belongs to, if any. Call list_initiatives for the IDs. To group epics under a new initiative, propose create_initiative and get a yes for it too.

7. Run the imports

Run one call for each epic:

• Import: import_project_from_jira_or_linear with provider: "jira", artifact_type: "epic", external_id, optional initiative_id and optional segment_ids (at most 20). Then call explore_build_projects with result.project_id.
• Link: link_project_jira_or_linear with project_id, external_url (the Jira epic URL) and fetch_from_provider: true.

To move an imported Project under an initiative later, call set_project_initiative.

Handle these errors:

• ALREADY_LINKED: the epic is already in Deck. Skip it and report it. For a link, details.linked_project_id names the Deck Project that has it.
• PROVIDER_NOT_CONNECTED: go back to step 2.
• PROVIDER_ARTIFACT_NOT_FOUND on a link: the epic URL is wrong. Ask the user for the correct URL.

8. Check the result

Call list_projects with external_provider: "jira". Run step 4 again. Each imported epic now shows its linked Deck Project.

Report the epics that you imported, linked and skipped, each with its deck_url.

Rules

• Show the plan and get a yes before you call write tools.
• Use only external_id values from list_projects. Never invent Jira epics.
• Imports read Jira and create Deck records only. Deck tools do not create or change anything in Jira. To create an epic, use the Deck web app or your own Jira tools, then call link_project_jira_or_linear.
• An identical import within 24 hours returns the first result and creates nothing new.
• Deck refreshes the title, status and owner of linked epics daily. Deck does not fill or sync Jira start and target dates. Documents and evidence stay in Deck.
• Quote Deck's numbers. Do not compute your own.
• If the user has more than one Deck organization, call select_organization first and pass org_id on every call.

Done when

• Each epic that the user picked is imported, linked or reported as skipped, with a reason.
• Each imported Project has a Deck link and the parent initiative that the user chose.
• The user knows the next step: link customer evidence with the roadmap evidence check.

See also: Jira, Projects, Initiatives and Model Context Protocol.