Modelling Support MCP server

Available in product edition: Professional Feature maturity: Beta

Introduction

The Modelling Support MCP server exposes the K5 design repository through the Model Context Protocol (MCP). AI-enabled clients and other integrations can discover element and relationship types, inspect GraphQL schema, read and update design data, read and change diagram content, manage the Git branch that holds the design, and use guided prompts—for example, to draft a design from an existing codebase.

This server is for external clients that need access to the design repository. To have the Design Assistant call tools on other MCP servers, see MCP support.

ℹ️Feature flag

The MCP server is only installed and exposed when the Helm value global.k5.featureFlags.modellingSupportMCPServerFlag is true. This is the default; set it to false to turn the feature off. See the installation configuration table.

Endpoint

Topic	Details
Base URL	{public-base-url}/diagram/mcp, where {public-base-url} is the externally reachable base path of your Solution Designer deployment (including any path prefix your environment uses). Example: https://workbench.mycompany.com/diagram/mcp.

ℹ️note

If the base URL of the MCP server is not working, your system administrator has most probably changed the routes. In this case, please contact your administrator for further advice.

Setup MCP server for usage

How you register the Modelling Support MCP server (URL, transport, headers, OAuth fields, config file location, and UI flows) depends on the MCP client you use. Follow that product’s supported transports, configuration schema, and authentication options; the sections below describe what this server expects so you can map them to your client.

Required configuration keys (for example type, url, headers, auth) and their exact structure are defined by the coding assistant, not by this MCP server. Always verify the expected config shape in your coding assistant documentation.

The subsections GitHub Copilot, Cursor, and IBM Bob describe how we connect each of these clients to this server. Each subsection links to that product’s own MCP documentation (file locations, transports, and full schemas).

Authentication

Protected MCP operations require exactly one of the following:

Method	Header	When to use
Personal access token (PAT)	K5-Access-Token: k5pat_…	Recommended for coding assistants and reverse engineering. Create the token in User settings → Access tokens.
OAuth / JWT	Authorization: Bearer <jwt>	Interactive or assisted OAuth against your identity provider, or a static JWT where the client supports it.

Do not send both headers on the same request. Personal access tokens must use the K5-Access-Token header—not Authorization. Tokens start with the prefix k5pat_.

If no valid credentials are supplied for a protected operation, the server responds with 401 Unauthorized. For JWT/OAuth clients, the response includes a WWW-Authenticate header that points at the protected-resource metadata endpoint (GET …/.well-known/oauth-protected-resource/mcp), in accordance with the Model Context Protocol (MCP) specification. PAT-based clients receive a plain unauthorized JSON response (no OAuth challenge), so the assistant does not start a browser login.

Summary for the assistants documented below

Coding assistant	How we connect to this server (details in each subsection)
GitHub Copilot	OAuth client in your identity provider — GitHub Copilot. You can also use a personal access token if your Copilot MCP config supports custom headers.
Cursor	Personal access token via K5-Access-Token (recommended) — Cursor. OAuth client remains an alternative.
IBM Bob	Static Bearer JWT (Authorization header) — IBM Bob. Prefer a PAT with K5-Access-Token if your Bob MCP config supports custom headers.

Personal access token (K5-Access-Token)

1. Create a token under User settings → Access tokens and copy the value (shown only once).
2. Add the Modelling Support MCP server to your coding assistant and set the header K5-Access-Token to that value. For examples see below

Rotate or revoke the token in User settings when it is no longer needed or may have been exposed.

OAuth client in your identity provider

Set up a dedicated OAuth client in your identity provider for the MCP integration and reference the client ID in the MCP server configuration of your coding assistant.

⚠caution

The required client settings (such as valid redirect URIs, grant types, and scopes) depend on the coding assistant you use. Consult your identity-provider and coding-assistant documentation to configure the client correctly.

This approach is not supported by every coding assistant.

If your identity provider supports dynamic client registration, your coding assistant may be able to register automatically without a pre-provisioned client; confirm in the GitHub Copilot and Cursor documentation linked in those sections.

Static Bearer token (JWT)

If OAuth-based flows are not available in your coding assistant, you can provide a valid JWT directly via the Authorization header in MCP server configuration. Field names and nesting depend on the client.

Providing the token statically bypasses the OAuth handshake entirely. The JWT must stay valid for your session; replace it when it expires.

ℹ️note

Do not put a personal access token (k5pat_…) in the Authorization header. Use K5-Access-Token instead.

For a concrete JWT configuration for IBM Bob (including transport type), see IBM Bob. Other assistants that accept a static Bearer token may use a different schema.

GitHub Copilot

Use GitHub’s documentation for where to add MCP servers, supported transports, and the full configuration schema: Extend GitHub Copilot Chat with Model Context Protocol (MCP) servers and the Using Model Context Protocol in your IDE overview.

Connect this server with an OAuth client in your identity provider (see Authentication). Add an entry to your MCP configuration (for example .vscode/mcp.json). When connecting, Copilot prompts you for the client ID:

{
  "servers": {
    "k5-workbench": {
      "url": "https://workbench.mycompany.com/diagram/mcp",
      "type": "http"
    }
  }
}

Cursor

Use Cursor’s Model Context Protocol (MCP) documentation for configuration file locations, transports, and all supported fields.

Recommended: Connect with a personal access token in .cursor/mcp.json:

{
  "mcpServers": {
    "k5-workbench": {
      "url": "https://workbench.mycompany.com/diagram/mcp",
      "headers": {
        "K5-Access-Token": "k5pat_<your-token>"
      }
    }
  }
}

Alternative: Connect with an OAuth client in your identity provider (see Authentication). Provide the client ID in your MCP configuration:

{
  "mcpServers": {
    "k5-workbench": {
      "url": "https://workbench.mycompany.com/diagram/mcp",
      "auth": {
        "CLIENT_ID": "your-mcp-client-id"
      }
    }
  }
}

IBM Bob

IBM Bob MCP documentation: Using MCP in Bob; transport details: MCP server transports.

Preferred: Use a personal access token with K5-Access-Token.

{
  "mcpServers": {
    "k5-workbench": {
      "url": "https://workbench.mycompany.com/diagram/mcp",
      "type": "streamable-http",
      "protocolNegotiation": "legacy",
      "headers": {
        "K5-Access-Token": "k5pat_<your-token>"
      }
    }
  }
}

💡tip

IBM Bob changed the default protocol negotiation for HTTP MCP servers. Later installations require "protocolNegotiation": "legacy" in the server config; without it, connections may time out. See Protocol negotiation.

JWT alternative: Connect with a static Bearer JWT via the Authorization header (see Static Bearer token (JWT) under Authentication). Set type to streamable-http at the same level as url and headers.

{
  "mcpServers": {
    "k5-workbench": {
      "url": "https://workbench.mycompany.com/diagram/mcp",
      "type": "streamable-http",
      "protocolNegotiation": "legacy",
      "headers": {
        "Authorization": "Bearer <jwt>"
      }
    }
  }
}

ℹ️note

It is also recommended to inject secrets via environment variables such as "K5-Access-Token": "${env:K5_ACCESS_TOKEN}" rather than hardcoding personal access tokens directly into the repository.

Other coding assistants may use different keys or nesting for a comparable setup; rely on each product’s documentation rather than relying on this structure.

Project scope in tool calls

Most tools require:

Argument	Purpose
acronym	K5 project acronym (see k5-project.yml — acronym). When the client is working in a local project repository, read this from k5-project.yml.
branch	Git branch that defines the design scope (usually the branch you are working on). When the client is working in a local repository, use the branch that is checked out locally.

Diagram tools also require diagramUuid, the UUID of the diagram to read or change.

For create-new-branch, branch is the name of the new branch and sourceBranch is the existing branch it is created from.

ℹ️note

Call the modelling and diagram tools on a branch that is already checked out in the Solution Designer. A branch that is not checked out causes those tools to fail with a 404 error. Use create-new-branch to create a branch, or checkout-changes-from-git to check one out, before calling the other tools on it.

Tools

The server exposes tools to discover types, read and change design data, work with diagrams, and manage the Git branch. Call get-partial-k5-graphql-schema before any GraphQL query or mutation, and build the document from the returned schema.

Discover types and schema

list-k5-element-types

Lists the element types available for the project and branch. Element types are the building blocks of a design.

When to use: Use this to see which element types exist before choosing what to model. Properties are omitted; retrieve them with get-k5-element-types-details.

Parameter	Type	Required	Description
acronym	string	yes	Project acronym.
branch	string	yes	Branch for which element types are resolved.

Response: JSON with an elementTypes array. Each entry has id, name, baseType, a short description, and an optional descriptionDetailed. baseType is one of default-model-element, composite-part, diagram, diagram-node-element-text, diagram-node-element-shape, diagram-node-element-note, diagram-node-element-image, or diagram-node-element-freehand. See Element base types for how each base type is created and used.

list-k5-relationships-types

Lists the relationship types available for the project and branch.

When to use: Use this to see which relationship types exist before connecting elements. Properties and allowed source/target combinations are omitted; retrieve them with get-k5-relationship-types-details.

Parameter	Type	Required	Description
acronym	string	yes	Project acronym.
branch	string	yes	Branch.

Response: JSON with a relationshipTypes array. Each entry has id, name, baseType, a short description, and an optional descriptionDetailed. baseType is default, aggregation, or composition. See Relationship base types.

get-k5-element-types-details

Returns properties, automatically set property keys, and the base type for the given element types.

When to use: Use this after list-k5-element-types when you need the property shape of specific element types before creating or editing instances.

Parameter	Type	Required	Description
acronym	string	yes	Project acronym.
branch	string	yes	Branch.
elementTypes	string[]	yes	Element type identifiers.

Response: JSON with elementTypesWithProperties. Each entry has elementTypeId, baseType, properties, and autoSetProperties (property keys the system sets on create or update).

Element base types

Base type	How instances are created and used
default-model-element	A standalone model element. Create and edit it with mutate-k5-element-instance. Place it on a diagram with defaultModelElementNodes of add-nodes-to-diagram.
composite-part	Exists only as part of an owning element, referenced by an elementReference or elementReferenceSelection property of that owner. Provide it inline when creating or editing the owner. The reference to the owner (omlParentId) is set automatically.
diagram	A diagram that shows model elements as nodes and relationships as edges. Read and change its content with the diagram tools.
diagram-node-element-text, diagram-node-element-shape, diagram-node-element-note, diagram-node-element-image, diagram-node-element-freehand	Diagram node elements (text, shape, note, image, or freehand) that exist on a diagram. Create, edit, and delete them the same way as default model elements, then place them on a diagram. Text, shape, and note nodes have dedicated lists on the diagram tools.

get-k5-relationship-types-details

Returns properties, the base type, automatically set property keys, and the allowed source and target element types for the given relationship types.

When to use: Use this when you need the property shape and the valid source/target combinations of specific relationship types before creating relationships.

Parameter	Type	Required	Description
acronym	string	yes	Project acronym.
branch	string	yes	Branch.
relationshipTypes	string[]	yes	Relationship type identifiers.

Response: A JSON array. Each entry has relationshipTypeId, baseType, properties, autoSetProperties, and allowedElements (resolved source and target element type identifiers). A relationship is valid when the element types of its source and target match one of those combinations. Only one relationship of the same type may exist between the same source and target.

Relationships are created and edited with mutate-k5-element-instance (createRelationship / editRelationship). Connect elements with sourceIdentifier and destinationIdentifier.

Relationship base types

Base type	Meaning
default	A general relationship between two elements.
aggregation, composition	The source element is a parent that contains the target. Elements with such a relationship can be nested on diagrams.

get-allowed-k5-relationships

For one element type, returns which relationship types are allowed by the OML configuration.

When to use: Use this to see which relationship types can connect instances of a given element type.

Parameter	Type	Required	Description
acronym	string	yes	Project acronym.
branch	string	yes	Branch.
elementType	string	yes	Element type identifier. Matched case-insensitively.

Response: JSON with an allowedRelationships array for that element type.

get-allowed-k5-relationships-for-element-types

Returns the allowed relationship types for several element types in one call.

When to use: Use this when you already know the element types in scope and want their allowed relationships together.

Parameter	Type	Required	Description
acronym	string	yes	Project acronym.
branch	string	yes	Branch.
elementTypes	string[]	yes	Element type identifiers. Matched case-insensitively.

Response: JSON with elementTypesWithAllowedRelationships. Each entry has elementTypeId and allowedRelationships.

get-partial-k5-graphql-schema

Returns the GraphQL schema as SDL for the project and branch. Optional filters keep the slice small.

When to use: Call this before query-k5-element-instances or mutate-k5-element-instance. Read the returned SDL for valid roots, fields, type names, and input types, then build the GraphQL document from that schema.

Parameter	Type	Required	Description
acronym	string	yes	Project acronym.
branch	string	yes	Branch for the schema.
elementType	string	no	Restrict to one element type (case-insensitive). If omitted, all element types are included when other filters allow it.
relationshipType	string	no	Restrict to one relationship type (case-insensitive). If omitted, all relationship types are included. Can be combined with elementType.
operationTypes	string[]	no	Include only these root operations: query, mutation. If omitted, both are included.
itemTypes	string[]	no	Include only: elements, relationships. If omitted, both are included.
operationNames	string[]	no	Root operation field names to include, for example elements, elementsByType, createElement, createRelationship, editRelationship. Use this when you already know the operation names. If set, only these operations and their related types are returned.

Response: SDL describing the requested GraphQL operations.

Read and change design data

query-k5-element-instances

Runs a GraphQL query against the given branch. The query must match the schema from get-partial-k5-graphql-schema.

When to use: Use this to read element and relationship instances from the current branch.

Parameter	Type	Required	Description
acronym	string	yes	Project acronym.
branch	string	yes	Branch for the query.
query	string	yes	GraphQL query document, derived from the schema.
variables	object	no	GraphQL variables. They must match the variables and input types of that schema.

Response: Instance data as requested in the GraphQL query.

mutate-k5-element-instance

Runs a GraphQL mutation to create, update, or delete element instances, or to create, update, or delete relationships, depending on the mutation you send. The mutation must match the schema from get-partial-k5-graphql-schema.

When to use: Use this to create, edit, or delete instance data on the current branch. Run mutation calls one after another. Several element creations can be combined into one mutation when the schema allows it.

Parameter	Type	Required	Description
acronym	string	yes	Project acronym.
branch	string	yes	Branch for the mutation.
mutation	string	yes	GraphQL mutation document, derived from the schema.
variables	object	no	GraphQL variables. They must match the variables and input types of that schema.

Response: Instance data as defined in the GraphQL mutation.

Diagram content

Diagram tools read and change what is drawn on an existing diagram. They take acronym, branch, and diagramUuid. To do the same work from the Design Assistant chat, see Diagram content.

Create the model elements and relationships first with mutate-k5-element-instance. Placing a node or edge draws an existing element or relationship; it does not create one. Removing a node or edge changes the diagram only. The model element or relationship stays in the design.

Call get-diagram-content before adding or updating, so new nodes do not overlap and updates start from the current nodes and edges.

Node and edge fields

Model element, note, shape, and text nodes share these fields:

Field	Required	Description
elementId	yes	UUID of the model element the node represents.
zIndex	yes	Stacking index of the node.
style.position.x, style.position.y	yes	Node coordinates.
style.width, style.height	no	Size. If omitted on add, the default for the visualization type or node type is used.

Model element nodes (defaultModelElementNodes) also take:

Field	Required	Description
visualizationType	yes	How the node is drawn. See the table below.
parentId	no	Id of the parent node when this node is nested inside an expanded parent. The parent must already be on the diagram. Add the parent first, then add children in a separate call.

visualizationType	Appearance	Default size (width × height)
card	Card with element type, label, and summary.	300 × 175
miniCard	Small card with element type and label. Size is fixed.	300 × 99
expanded	Large card that can contain other nodes. Use it for elements that are parents through an aggregation or composition relationship.	480 × 320
textual	Large card that shows description text and allows editing it on the card.	600 × 700

Note, shape, and text nodes have their own lists. Default size (width × height) is 320 × 240 for a note, 175 × 175 for a shape, and 300 × 60 for text.

Extra field	Node lists	Description
backgroundColor	note, shape, text	Background color.
opacity	shape, text	0 (transparent) to 100 (opaque).
rotation	shape, text	Degrees, 0 to 360.
titlePosition	shape	top, bottom, or center.

Update tools require id (the placed node or edge id) on every entry. Each entry replaces the stored node or edge, so send the complete object. On a node update, omitted width and height are reset to the defaults above, and an omitted parentId moves the node out of its parent.

Edges (edges) use:

Field	Required	Description
id	on update	Id of the placed edge.
relationshipId	yes	UUID of the relationship to draw.
source, target	yes	Ids of the nodes the edge connects. Use nodes that represent the source and target elements of the relationship.
sourceHandle	yes	top-source, bottom-source, left-source, or right-source. Choose the handle from the relative node positions.
targetHandle	yes	top-target, bottom-target, left-target, or right-target.
zIndex	yes	Stacking index of the edge.
style	no	Edge styling. On add, omitted values fall back to the relationship type. On update, omitted style values are cleared and do not fall back to the relationship type.

style fields: color; stroke (line, dashed, dotted, bold); strokeWidth; markerStart and markerEnd (arrow, arrow_filled, circle, circle_filled, diamond, diamond_filled, none, reverse_triangle, reverse_triangle_filled, simple_arrow); arrowType (bezier, straight, step, smoothstep).

get-diagram-content

Returns the nodes and edges placed on a diagram, in the same shape that update-nodes-on-diagram and update-edges-on-diagram accept.

When to use: Use this before placing or changing diagram content, and whenever you need the current layout.

Parameter	Type	Required	Description
acronym	string	yes	Project acronym.
branch	string	yes	Branch.
diagramUuid	string	yes	UUID of the diagram.

Response: JSON with uuid, optional identifier, defaultModelElementNodes, noteNodes, shapeNodes, textNodes, and edges. Node style includes position, width, and height. Each edge includes relationshipId, source, target, handles, zIndex, and style.

add-nodes-to-diagram

Places existing model elements on a diagram as nodes.

When to use: Use this to visualize elements that already exist. Edges are not drawn automatically; add them with add-edges-to-diagram.

Parameter	Type	Required	Description
acronym	string	yes	Project acronym.
branch	string	yes	Branch.
diagramUuid	string	yes	UUID of the diagram.
defaultModelElementNodes	object[]	no	Model element nodes. See Node and edge fields.
noteNodes	object[]	no	Note nodes.
shapeNodes	object[]	no	Shape nodes.
textNodes	object[]	no	Text nodes.

Response: JSON with success, diagramUuid, and the same node lists. Each entry has the generated id and its elementId, in the same order as the input list.

add-edges-to-diagram

Places existing relationships on a diagram as edges between nodes that are already on it.

When to use: Use this after the endpoint nodes are placed.

Parameter	Type	Required	Description
acronym	string	yes	Project acronym.
branch	string	yes	Branch.
diagramUuid	string	yes	UUID of the diagram.
edges	object[]	yes	Edges to place. See Node and edge fields.

Response: JSON with success, diagramUuid, and edges. Each entry has the generated id, relationshipId, source, and target, in the same order as the input.

update-nodes-on-diagram

Replaces nodes that are already on a diagram, for example to move, resize, restyle, or nest them.

When to use: Use this to change placed nodes. Start from the objects returned by get-diagram-content and send each node in full.

Parameter	Type	Required	Description
acronym	string	yes	Project acronym.
branch	string	yes	Branch.
diagramUuid	string	yes	UUID of the diagram.
defaultModelElementNodes	object[]	no	Model element nodes to replace. Each entry requires id.
noteNodes	object[]	no	Note nodes to replace. Each entry requires id.
shapeNodes	object[]	no	Shape nodes to replace. Each entry requires id.
textNodes	object[]	no	Text nodes to replace. Each entry requires id.

Response: JSON with success, diagramUuid, and the updated node lists.

update-edges-on-diagram

Replaces edges that are already on a diagram.

When to use: Use this to change placed edges. Start from the edges returned by get-diagram-content and send each edge in full.

Parameter	Type	Required	Description
acronym	string	yes	Project acronym.
branch	string	yes	Branch.
diagramUuid	string	yes	UUID of the diagram.
edges	object[]	yes	Edges to replace. Each entry requires id. See Node and edge fields.

Response: JSON with success, diagramUuid, and the updated edges.

remove-nodes-from-diagram

Removes nodes from a diagram. The model elements stay in the design. Child nodes nested inside a removed expanded node are removed as well. Edges connected to a removed node are removed as well. To keep a nested child, move it out with update-nodes-on-diagram first.

When to use: Use this to take nodes off a diagram without deleting the underlying elements.

Parameter	Type	Required	Description
acronym	string	yes	Project acronym.
branch	string	yes	Branch.
diagramUuid	string	yes	UUID of the diagram.
nodeIds	string[]	yes	Ids of the placed nodes to remove.

Response: JSON with success, diagramUuid, removedNodeIds (including nested children), and removedEdgeIds.

remove-edges-from-diagram

Removes edges from a diagram. The relationships stay in the design, and the connected nodes stay on the diagram. To remove nodes together with their edges, use remove-nodes-from-diagram.

When to use: Use this to take relationship lines off a diagram without deleting the relationships.

Parameter	Type	Required	Description
acronym	string	yes	Project acronym.
branch	string	yes	Branch.
diagramUuid	string	yes	UUID of the diagram.
edgeIds	string[]	yes	Ids of the placed edges to remove.

Response: JSON with success, diagramUuid, and removedEdgeIds.

Git

These tools create a branch, check a branch out into the workbench, or commit and push the design changes on a branch. They use the same authentication as the other tools.

create-new-branch

Creates a new Git branch (track) from an existing source branch.

When to use: Use this when design work should happen on a new branch. Permission is checked on the source branch.

Parameter	Type	Required	Description
acronym	string	yes	Project acronym.
branch	string	yes	Name of the new branch.
sourceBranch	string	yes	Existing branch to create it from.

Response: JSON with success, acronym, branch, sourceBranch, and a message.

checkout-changes-from-git

Checks a project branch out from Git into the diagram modeller and refreshes the model from the remote branch.

When to use: Use this to load a branch into the workbench before calling the modelling or diagram tools on it.

Parameter	Type	Required	Description
acronym	string	yes	Project acronym.
branch	string	yes	Branch to check out.
force	boolean	no	Defaults to true. Set to false to refuse checkout when the local track has unsaved state.
reset	boolean	no	Defaults to true. Set to false to keep local divergence from the remote branch.
isDefaultBranch	boolean	no	When true, treats the branch as the project default branch during checkout.

⚠caution

force and reset both default to true, so a checkout discards unsaved local state and resets the track to the remote branch.

Response: JSON with success, acronym, branch, and a message.

commit-changes-to-git

Commits and pushes all design instance changes on a project branch.

When to use: Use this after modelling or diagram changes should be stored in Git.

Parameter	Type	Required	Description
acronym	string	yes	Project acronym.
branch	string	yes	Branch to commit.
comment	string	yes	Commit message.
isForceCommit	boolean	no	When true, commits even if there are warnings.

Response: JSON with success, acronym, and branch. A clean commit includes a message. A commit that reports problems includes a problems field.

Prompts

generate-k5-design-from-code

Guided workflow to produce a K5 design from an existing codebase (reverse engineering). The prompt steers the model to discover types and schema, analyse code, confirm with the user, and create or update elements and relationships through the tools above. After the model is written, the same prompt can place that result on one or more diagrams with add-nodes-to-diagram and add-edges-to-diagram, once you confirm the diagram scope.

The same tools can also be used from a normal chat message to compare an existing design with the implementation and update the design after confirmation. See Align an existing design with the implementation.

For more information please check Reverse Engineering.