Jira integration example

Available in product edition: Professional

Introduction

This page is a worked example. The product does not ship a built-in Jira connector. You assemble the integration from capabilities that are already in the workbench:

1. An administrator registers the Atlassian Rovo MCP server as an external system.
2. Each user authenticates with a personal API token in an Authorization header — Basic authentication, not OAuth. See custom MCP settings.
3. You declare external proxy element types in an OML profile so Jira work items can appear in the model, with a link property that points to the original issue.

The Design Assistant is the MCP client. When you @ mention the registered system, it loads Rovo's tools and can read Jira (and, if allowed, write back).

The same Rovo connection can also reach other Atlassian apps, such as Confluence. This example stays on Jira.

What you need

• Atlassian Cloud with access to the Rovo MCP server.
• An Atlassian organization admin who has enabled API token authentication for Rovo MCP. The Design Assistant cannot complete an OAuth consent flow.
• A workbench administrator who can register external systems.
• A personal Atlassian API token with the Jira agent-interface scopes you need.
• An OML profile that defines the external proxy element types you want, included in the project's baseline.
• Design Assistant credentials, as for any other assistant use. See prerequisites.

Register the Rovo MCP server

An administrator registers one shared MCP connection. Users do not create the endpoint themselves.

1. Open Admin settings → External systems.
2. Click Add external system.
3. Fill in:

Field	Example
Name	Jira — this is the label users see in the mentions picker. It must be unique.
MCP Endpoint URL	https://mcp.atlassian.com/v2/mcp
Description	Optional. For example: Atlassian Rovo MCP — Jira work items for design context.
Timeout (ms)	High enough for Jira lookups. Increase it if tool calls time out.
Enabled	On

4. Leave personal credentials out of this form. Do not put an Authorization header here unless you intentionally share one service-account key with every user.
5. Click Add.

💡tip

If a Rovo tool requires a cloudId (your Atlassian Cloud site ID) and the assistant asks for it repeatedly, add it as a default argument — on the admin system when everyone uses the same site, or in each user's custom MCP settings otherwise. API-token authentication is not bound to a single site the way an OAuth consent is.

ℹ️note

The Design Assistant MCP client supports neither OAuth nor dynamic client registration. Rovo's default interactive sign-in will not work here. You must use authentication via API token.

If the assistant connects but does not list individual Jira tools, try https://mcp.atlassian.com/v2/mcp?tools=all. That asks Rovo to expose a flat tool list instead of the discover/execute pattern. See Atlassian's getting started guide.

The platform must be able to reach mcp.atlassian.com. If your Atlassian organization uses an IP allowlist, allow the platform's egress addresses — MCP calls are made by the Design Assistant, not by the user's browser.

Configure the Authorization header

Each user who should call Jira from the assistant stores their own token. The assistant then acts with that user's Atlassian permissions.

Enable API token authentication (Atlassian org admin)

In Atlassian Administration: Rovo → Rovo MCP server → Authentication, turn API token on.

If this is off, header-based calls from the Design Assistant are rejected. Users cannot fall back to OAuth in this product.

Create a personal API token

1. Open Atlassian API tokens while signed in as the user who will use the assistant.
2. Create a token and select the Rovo agent-interface scopes. For typical design work (read and search Jira), start with:
   • read:jira:agent-interface
   • search:jira:agent-interface
3. Add write:jira:agent-interface only if writing tools are allowed in your deployment and you intend to change Jira from the assistant. See Read-only and write tools.
4. Copy the token once. Note the email address of the Atlassian account that owns it.

A classic Jira REST token without these scopes will not authorize Rovo MCP. Details and the full scope list: Configuring authentication via API token.

Encode Basic credentials

Rovo expects HTTP Basic authentication for a personal token. The header value is Basic plus a Base64 encoding of email:api_token — not a Bearer token.

# Format: email:api_token
echo -n "your.email@example.com:YOUR_API_TOKEN_HERE" | base64

On Windows PowerShell:

[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("your.email@example.com:YOUR_API_TOKEN_HERE"))

The result is a single string. The header value you store is:

Basic BASE64_ENCODED_EMAIL_AND_TOKEN

Replace BASE64_ENCODED_EMAIL_AND_TOKEN with the output of the command. Keep the space after Basic.

⚠caution

Authorization: Bearer … is for an Atlassian service-account API key, not for a personal API token. Sending a personal token as Bearer will fail.

Store the header in User settings

1. Open User settings from the header Settings icon, then the External systems tab.
2. Click Add custom MCP setting.
3. Name: select the system the administrator registered (for example Jira).
4. Under Headers, add:

Field	Value
Key	Authorization
Value	Basic followed by your Base64 string
Secure	On

5. Leave Enabled on. Click Add.

Mark the value Secure so it is not shown again after save. The user header is sent in addition to any admin headers; it does not replace the endpoint URL.

You only see your own custom MCP settings. Other users add their own tokens the same way.

Represent Jira work items as external proxy elements

Connecting MCP lets the assistant read Jira during a chat. It does not, by itself, put issues on the canvas. For that, define external proxy element types in your OML profile (baseType: "external-proxy-element").

The proxy is a representation in your model. Jira remains the source of truth. There is no live replica: the element is Git-backed design data until you or the assistant update it.

Choose types that match how you design — for example one type per Jira work type (epic, story, bug), or one coarser type that gathers several items.

Use a link property for the URL of the original work item. In details it is shown as a clickable hyperlink.

elementTypes:
  - id: "ext.jira-story"
    name: "Jira story"
    description: "A Jira story that is relevant for this design. The original work item is managed in Jira."
    descriptionDetailed: "Use this type for a single Jira story that should appear in the model. Do not use it for epics, or for a requirement that gathers several Jira items."
    baseType: "external-proxy-element"
    layer: "business"
    propertiesSchema:
      - "jira-story-fields"

propertyGroups:
  - id: "jira-story-fields"
    name: "Jira story fields"
    properties:
      - fieldName: "source"
        displayName: "Source"
        description: "Opens the original Jira work item."
        type: "link"
      - fieldName: "issue-key"
        displayName: "Issue key"
        description: "Jira issue key, for example PROJ-123."
        type: "text"
      - fieldName: "status"
        displayName: "Status"
        description: "Status copied from Jira when the proxy was last updated."
        type: "text"

Add the profile to the project's baseline so the types are available. You can also define relationship types — for example that a domain entity realises a Jira story — whenever the design needs that connection. See Relationships.

Editing the proxy in the workbench changes only the model. It does not update Jira.

Use it in the Design Assistant

1. Confirm your custom MCP setting is enabled and the Authorization header is set.
2. Open the Design Assistant in a project whose baseline includes the proxy types.
3. Type @ and pick the system from the External systems section of the mentions picker. Typing the name in plain text is less reliable than inserting the mention.

Using @Jira, summarise the open stories in project PROJ that affect this design

Using @Jira, create Jira story external proxy elements for the open stories in PROJ
and fill source, issue-key, and status from each work item

The second prompt updates the model. It does not change Jira.

Using @Jira, refresh the properties on the existing Jira story proxies from the current work items

Refresh is a design action you ask for, not a background sync.

Using @Jira, add a comment on PROJ-123 with a short summary of the current design

Writing tools run only if k5-design-assistant.externalSystemsReadOnly is false. Keep the default (true) unless you are certain that writing to Jira should be allowed. See MCP support and installation configuration.

Replace Jira with the name your administrator registered, and PROJ with your Jira project key.

Boundaries

• This is an example composition, not a dedicated Jira product. Types, properties, and which issues you proxy are yours to define.
• OAuth is not supported. Credentials must be an Authorization header. Personal tokens use Basic auth (email:api_token Base64-encoded).
• Atlassian organization admins must enable API token authentication for Rovo MCP.
• By default the assistant executes only read-only MCP tools. Creating or updating issues in Jira requires both write scopes on the token and k5-design-assistant.externalSystemsReadOnly: false.
• What the assistant can read or change is limited by Rovo's tools and by the permissions of the token it sends.
• An external proxy element is not kept in lockstep with Jira. Opening the link property goes to Jira; it does not refresh the other fields.
• Changing a proxy does not change Jira. The reverse requires MCP write tools.
• MCP calls originate from the platform. Browser IP is irrelevant for allowlists.
• Atlassian may consume Rovo credits for MCP tool calls.

Related documentation

• MCP support — how the Design Assistant uses MCP tools
• External systems — register the Rovo endpoint (administrators)
• Manage custom MCP settings — personal Authorization header
• External proxy elements — represent Jira work items in the model
• Link properties — URL fields such as source
• Atlassian: Get started with the Rovo MCP server
• Atlassian: Configure authentication via API token