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 runs them as needed to complete your request.

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. Tools that write to it are executed only if your administrator allows them — by default they are not. 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 executes them while working through your prompt.

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 executes only read-only MCP tools — those the server annotates with readOnlyHint set to true. Tools that can write to the external system are not run.

Writing tools are executed only if the Helm value k5-design-assistant.externalSystemsReadOnly is set to false. See installation configuration. Keep the default (true) unless you are certain that writing tools should be allowed.

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 — and, by default, only the read-only ones. 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 and your installation allows writing MCP tools. By default this is not enabled. Examples include adding a comment, updating a ticket, or creating a follow-up item.
  • 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.
  • 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.

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