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}/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/mcp`.

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.

For general MCP host configuration (where to add servers, file locations, transports), see the documentation of the coding assistants we mainly test with this server:

GitHub Copilot — Extend GitHub Copilot Chat with Model Context Protocol (MCP) servers (see also the Using Model Context Protocol in your IDE overview in GitHub Docs).
Cursor — Model Context Protocol (MCP) in the Cursor documentation.
IBM Bob — Using MCP in Bob in the IBM Bob documentation (transport details: MCP server transports).

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 to provide a valid token to the MCP server:

using an OAuth client in your identity provider
providing a Bearer token statically (for example via an Authorization header)

The following summarises how we connect example coding assistants to this server today (your client may expose additional options; use its documentation if something is not listed here).

Coding assistant	Supported approach
GitHub Copilot	OAuth client (identity provider)
Cursor	OAuth client (identity provider)
IBM Bob	Static Bearer token (`Authorization` header)

A dash (—) means we do not document that combination for the assistant in this guide; your MCP client may still offer it—confirm in that product’s MCP documentation.

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 (e.g. for IBM Bob), 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.

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.

Introduction​

Endpoint​

Setup MCP server for usage​

Authentication​

OAuth client in your identity provider​

Static Bearer token​

Project scope in tool calls​

Tools​

list-k5-element-types​

get-allowed-k5-relationships​

get-k5-element-types-details​

get-partial-k5-graphql-schema​

query-k5-element-instances​

mutate-k5-element-instance​

Prompts​

generate-k5-design-from-code​