Modelling Support MCP server

Available in product edition: Professional

⚠Beta

The Modelling Support MCP server is in beta. It is intended for any consumer that integrates with Solution Builder, but behaviour, tools, and responses may change in future releases. Plan for upgrades and avoid hard-coding assumptions beyond the documented contract.

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 types, inspect GraphQL schema, read and update design data, and use guided prompts—for example, to draft a design from an existing codebase.

The server is offered by the diagram modeller service when GraphQL / modelling is enabled for your deployment.

Endpoint

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

Authentication

The MCP server supports OAuth and expects a valid JWT from the identity provider used across your Solution Builder deployment.

If no valid Bearer token is supplied, the server responds with 401 Unauthorized and a WWW-Authenticate header that points clients at the protected-resource metadata endpoint (GET …/.well-known/oauth-protected-resource/mcp), in accordance with the Model Context Protocol (MCP) specification.

There are multiple ways to provide a valid token to the MCP server:

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. It has been verified to work with GitHub Copilot and Cursor, among others.

GitHub Copilot — add an entry to your MCP configuration (e.g. .vscode/mcp.json). When connecting, Copilot prompts you for the client ID:

{
  "servers": {
    "my-design-server": {
      "url": "https://design.example.com/mcp",
      "type": "http"
    }
  }
}

Cursor — provide the client ID directly in the MCP configuration (e.g. .cursor/mcp.json):

{
  "mcpServers": {
    "my-design-server": {
      "url": "https://design.example.com/mcp",
      "auth": {
        "CLIENT_ID": "your-mcp-client-id"
      }
    }
  }
}

Alternatively, if your identity provider supports dynamic client registration, the coding assistant can register itself automatically and no explicit client setup is needed.

Static Bearer token

If OAuth-based flows are not available in your coding assistant, you can provide a valid JWT directly via the Authorization header in your MCP server configuration:

{
  "mcpServers": {
    "my-design-server": {
      "url": "https://design.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <jwt>"
      }
    }
  }
}

This bypasses the OAuth handshake entirely. Make sure the token stays valid for the duration of your session; you will need to replace it once it expires.

Work with your security team so OAuth clients, scopes, and token lifetimes match your environment's policies.

Project scope in tool calls

Most tools require:

Argument	Purpose
acronym	K5 project acronym (see k5-project.yml — acronym).
branch	Git branch that defines the design scope (usually the branch you are working on).

ℹ️note

It is required that the chosen branch is already checked out in the Solution Builder, otherwise the tools will be failing with a 404 error.

Tools

Please find below the available tools.

list-k5-element-types

Lists available element types and their schema for the given project and branch (building blocks of the design and their properties).

When to use: Use this when you want to get to know which elements are available and can be used for designing.

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

Response: JSON including an elementTypes field, describing the available element types from your enabled OML profiles.

get-allowed-k5-relationships

For one element type, returns which relationship types are allowed (from OML configuration), including valid connection patterns for modelling.

When to use: Use this when you want to get to know which relationship types are available for a given element type to understand how the instances can be related to each other.

Parameter	Type	Required	Description
acronym	string	yes	Project acronym.
branch	string	yes	Branch.
elementType	string	yes	Element type to inspect.

Response: JSON describing allowed relationships for the given element type.

get-k5-element-types-details

Returns detailed property information for the given K5 element types.

When to use: Use this when you want to get to know the available properties that are defined for the given element type(s), to understand the format of the element instances.

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

Response: JSON including elementTypesWithProperties, describing the available properties for the given list of element types.

get-partial-k5-graphql-schema

Returns the GraphQL schema as SDL. Optional filters limit operations, item kinds, or a single element type.

When to use: Use this when you want to perform a graphql query or a graphql mutation operation on the instance data - this way you can ensure that you provide a valid schema to the graphql endpoint.

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.
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.
operationName	string	no	Restrict schema to a certain operation, identified by the name. Use this if you know the exact name of the operation already.

Response: SDL (Schema Definition Language) describing the available GraphQL operations.

query-k5-element-instances

Runs a GraphQL query to find element instances from the given branch. The sent query has to fit to schema returned by get-partial-k5-graphql-schema.

When to use: Use this when you want to query instance data 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.
variables	object	no	GraphQL variables.

Response: Instance data as requested in GraphQL query.

mutate-k5-element-instance

Runs a GraphQL mutation to create, update, or delete one element instance or apply relationship mutations, depending on the mutation you send. The sent mutation has to fit to schema returned by get-partial-k5-graphql-schema.

When to use: Use this when you want to mutate (create, edit, delete) instance data from the current branch.

Parameter	Type	Required	Description
acronym	string	yes	Project acronym.
branch	string	yes	Branch for the mutation.
mutation	string	yes	GraphQL mutation document.
variables	object	no	GraphQL variables.

Response: Instance data as defined in GraphQL mutation.

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.

For more information please check Reverse Engineering.