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 Designer, 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.

ℹ️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://design.example.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

The MCP server supports OAuth and expects a valid JWT from the identity provider used across your Solution Designer 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 for a coding assistant to end up supplying that token:

• using an OAuth client in your identity provider (interactive or assisted OAuth in the assistant)
• providing a Bearer token statically (for example via an Authorization header in MCP server configuration)

How you configure either approach is defined by your MCP host; map the server behaviour above to the options your assistant exposes.

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
Cursor	OAuth client in your identity provider — Cursor
IBM Bob	Static Bearer token (Authorization header) — IBM Bob

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. For this server we document it under GitHub Copilot and Cursor.

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

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 token must stay valid for your session; replace it when it expires.

For a concrete 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": {
    "my-design-server": {
      "url": "https://design.example.com/diagram/mcp",
      "type": "http"
    }
  }
}

Cursor

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

Connect this server with an OAuth client in your identity provider (see Authentication). Provide the client ID in your MCP configuration (for example .cursor/mcp.json):

{
  "mcpServers": {
    "my-design-server": {
      "url": "https://design.example.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.

We connect this server to Bob using a static Bearer token via the Authorization header (see Static Bearer token under Authentication). Set type to streamable-http at the same level as url and headers.

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

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).
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 Designer, 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.