Skip to main content

MCP support

Available in product edition: Professional

Introduction​

The Design Assistant can work with systems outside the current project by calling tools that those systems expose through the Model Context Protocol (MCP). Administrators register each MCP server as an external system. When you mention that system in chat, the assistant loads the server's tools and uses them to complete your request. Before it calls a tool, it asks you to allow that call.

Any server that implements the MCP specification can be connected — not only a particular issue tracker or requirements tool. Typical connections include wikis, ticket systems, and other services in your development lifecycle. The assistant can use tools that read from the connected system and tools that write to it. Each call asks for your consent before it runs. An administrator can restrict the assistant to read-only tools. For a complete walkthrough with Jira and the Atlassian Rovo MCP server, see the Jira integration example.

This is the opposite direction from the Modelling Support MCP server, which exposes the design repository to external coding assistants. Here, the Design Assistant is the client: it calls tools on MCP servers that you have connected.

How the assistant uses MCP tools​

  1. An administrator registers the MCP server in Admin settings → External systems (name, endpoint, shared headers, timeout, and whether it is enabled).
  2. If the server needs your credentials, you add them as custom MCP settings — typically a personal API key in an Authorization header.
  3. In the Design Assistant chat, @ mention the external system from the External systems section of the mentions picker.
  4. The assistant fetches the tools from that MCP server and uses them while working through your prompt.
  5. Before each tool call, it asks for your consent, unless you have already allowed that tool permanently or for the current chat session. See Consent before an MCP tool runs.

The assistant sends the configured API keys and headers on those calls. When you have custom MCP settings enabled for a system, those personal headers and default arguments apply to your requests, together with the shared administrator configuration. Connection details such as the MCP endpoint URL and timeout always come from Admin settings.

Authorization​

The design assistant MCP client supports neither OAuth nor dynamic client registration in the current version. Authorization credentials must be provided as headers — shared values in Admin settings → External systems, or personal values in custom MCP settings. That is the only supported way to authenticate MCP calls.

Read-only and write tools​

By default, the assistant lists and can execute both read-only and writing MCP tools. A tool is read-only when the server annotates it with readOnlyHint set to true. Writing tools can change data in the external system. Every call, including a read, still asks for your consent before it runs.

Set the Helm value k5-design-assistant.externalSystemsReadOnly to true to list and execute only read-only tools. See installation configuration. The default is false.

The installation setting still applies after you allow a tool. If writing tools are disabled, the assistant does not run them.

Before the assistant calls a tool on an external system, it pauses and asks whether that call may run. The question appears in the assistant's working steps in the chat.

Each question covers one tool on one external system. E.g. a search tool on Jira, a different tool on Jira, and a tool with the same name on another system are separate decisions. Read-only calls ask as well, unless you have already allowed that tool.

What the step shows​

The step states which tool is about to be called and the reason for it. This helps the user decide whether a tool shall be executed or not.

FieldWhat it shows
External SystemThe registered system this call would use.
Read-onlytrue or false. The tool's readOnlyHint: whether the tool only reads.
Destructivetrue or false. The tool's destructiveHint: whether the tool may perform destructive updates.
InputThe arguments the tool would be called with, as formatted JSON.

Check Read-only, Destructive, and Input before you allow a call that can change the external system.

The choices sit under the label Tool consent. The assistant decides which choices to offer. The offered choices always appear in this order:

ChoiceWhat it does
Don't allowThis call does not run. The assistant can ask about the same tool again later. The choice is not stored.
Allow onceThis call may run. The next call of the same tool asks again. The choice is not stored.
Allow alwaysThis call may run. The tool is saved as allowed for you on this external system. Later calls of that tool skip the question until you revoke the consent.
Allow for this sessionThis call may run, and later calls of the same tool on the same system may run for the rest of this chat session. A new session asks again. The choice is not stored in User settings.

When Allow for this session is offered, it is the primary button.

Allow for this session is kept with that conversation on the server, not in User settings. It stays for 24 hours after the last message in that conversation. Closing the sidebar session leaves it in place. A new session is a new conversation and asks again. See Multiple sessions.

After you allow the call​

The assistant continues, and the tool's result is added to the same step under Response. The request and the result stay together.

When the assistant finishes, the working steps collapse into Agent worked, or Agent worked for N s when a duration is shown. Open that block again to see the consent step and the tool result.

Where a permanent allow is kept​

Only Allow always is listed in User settings. Allow for this session stays with that conversation on the server for 24 hours after the last message. Don't allow and Allow once are not kept.

A saved consent belongs to your user account. Each user allows tools for their own calls.

Review and revoke them under User settings → External systems, on the external system's MCP tools tab. From the Design Assistant header, open the settings menu and choose Custom MCP Settings to open that page in a new browser tab.

Consent is given in the chat. The settings page lists tools you have already allowed permanently, and it is where you revoke them. Changing your headers, default arguments, or the enabled state for a system leaves those consents in place.

Mentioning an external system​

Type @ in the chat input. The mentions picker includes an External systems section that lists the MCP connections available to you. Select a system to insert a mention.

Use a mention whenever you want the assistant to work with that system. The mention is an explicit instruction to load that server's tools. Typing the system name in plain text is less reliable than inserting the mention from the picker.

For picker behaviour (search, chips, keyboard), see Mentions.

What you can do​

The assistant can only run the tools the connected MCP server actually exposes. By default that includes writing tools. Within that set, typical tasks include:

  • Read information and use it in the current design conversation — for example summarise open issues, fetch a requirements page, or look up items that should be reflected in the model.
  • Write back to the connected system when the server offers write tools. Examples include adding a comment, updating a ticket, or creating a follow-up item. An administrator can turn writing tools off.
  • Combine external data with design work in the current project — for example mention the system, pull the relevant items, and create or update external proxy elements so that information stays available in the model.

The Design Assistant does not add extra operations of its own for that system.

Boundaries​

  • Only MCP servers that an administrator has registered as an external system, and that are enabled, are available in the assistant.
  • Every tool call needs your consent, unless you have already allowed that tool with Allow always or Allow for this session. Consent is per tool and per external system. See Consent before an MCP tool runs.
  • You cannot register a new MCP endpoint in User settings. You can only add personal headers and default arguments on top of an existing system.
  • OAuth and dynamic client registration are not supported. Credentials must be supplied as headers in Admin settings or in your custom MCP settings.
  • Mention the system so the assistant loads and uses its tools.
  • What the assistant can read or change in the external system is limited by that server's tools and by the permissions of the credentials it sends.
  • When writing tools are allowed, they can change data outside the workbench. That is different from cross-project support, where the assistant can only write design data in the project and branch you currently have open.
  • The connected server must implement the MCP specification and be reachable from the platform.
  • MCP support does not replace design recipes. Recipes add skills and commands for design work; MCP tools are additional operations from an external server.

Example prompts​

Replace the system names with the names your administrator registered. If the MCP server requires your credentials, add them first under User settings → External systems and mark sensitive values as Secure. The first time a prompt needs a tool, the chat asks you to allow that call.

Using @Jira, summarise the open issues related to this project
Using @Confluence, fetch the requirements from "Order management" and extend the current design to cover them
Using @Jira, create external proxy elements for the open stories in this project and fill the properties defined on the type

This updates the model in the current project. It does not change Jira. See External proxy elements and the Jira integration example.

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