MCP Server
Introduction
The MCP Server module provides easy low-code capability to set up MCP (Model Context Protocol) server within a Mendix app. An MCP server can seamlessly expose resources (such as tools or prompts) to other external AI applications that support MCP. The Mendix MCP Server module builds a bridge between Mendix and MCP client applications such as Claude Desktop, through the MCP Java SDK. With the current implementation, it is possible to:
- Expose reusable prompts including the ability to use prompt parameters
- List and execute microflow implemented in the application as tools
To use function calling within the same Mendix application and integrating to an LLM, consider function calling.
Limitations
The current version has the following limitations:
- Tools can only return a
TextContent
result. - The client connection remains active for only 15 minutes, as the Mendix runtime currently does not support async requests.
- User authorization can currently only be applied on request but not at the tool/prompt level. As a result, the current user is not available within tool/prompt microflows, and entity access or XPath constraints can not be enabled out of the box. This is due to the capabilities offered by the official MCP Java SDK which does not support reusing a Mendix user session in the executed tools/prompts.
Note that the MCP Server module is still in its early version and latest versions may include breaking changes. Since both the open-source protocol and the Java SDK are still evolving and regularly updated, these changes may also affect this module.
Installation
If you are starting from the Blank GenAI app template, the MCP Server module is already included and does not need to be downloaded manually.
If you start from a standard Mendix blank app, or have an existing project, you must install the MCP Server module manually. Follow the instructions in How to Use Marketplace Content to install the MCP Server module from the Marketplace.
Configuration
Create MCP Server
The Create MCP Server
action initializes an MCP server in the Mendix runtime, creates and returns the MCPServer
object. You can use the created MCPServer
to add tools or prompts. The Path
attribute determines how external systems can reach the MCP server, that means this value needs to be known to the the MCP Client (usually set in a configuration file). After the action gets triggered, the server becomes available for external clients to connect. As mentioned in the limitations section above, the connection remains active for only 15 minutes.
Based on your use case, this action can be triggered manually by an admin if wrapped around a microflow accessible in the UI, via an after start-up microflow, or by any other microflow such as a scheduled event.
For examples, see the Example Implementations
folder inside of the module which contains logic to create a server, add an authentication microflow, and expose a tool and prompt.
Enable Authentication
If no authentication is enabled for the MCP Server, it can be accessed by any service without being authorized specifically. Be aware that this is not recommended for applications running on the public cloud. Currently, selecting a microflow is required. For test purposes however, you can just delete the content of the attribute after setting up the MCP Server if you do not want to enable authentication. There is a corresponding example in the GenAI Showcase app, where the ACT_MCPServerConfiguration_InitializeMCPServer
microflow shows how this can be done.
For most cases, you want to ensure that MCP clients need to be authorized before using any resources from the MCP Server or even discover what resources are available. To enable authentication, you can specify a microflow in the Create MCP Server
action. The microflow is executed each time a request is processed by the MCP Server.
The selected microflow must adhere to the following principles:
- The Input type should be
MCPServer
and/orSystem.HttpRequest
, to extract required values, such as HttpHeaders from the request. - The return value needs to be a
System.User
object which represents the user who sent the request.
Inside of your microflow, you can implement your custom logic to authenticate the user. For example, you can use username and password (basic auth), Mendix SSO, or external identity providers (IdP) as long as a User
is returned. Note that the example authentication microflow within the module only implements the most basic authentication.
Protocol Version
When creating an MCP server, you need to specify a ProtocolVersion
. On the official MCP documentation, you can review the differences between the protocol versions in the changelog. The MCP Server module currently only supports v2024-11-05
and the HTTP+SSE transport. MCP Clients, that need to connect to a Mendix MCP server, should support the same version. Note that Mendix follows the offered capabilities of the MCP Java SDK.
Add Tools
After the Create MCP Server action, you can add one or multiple microflows as Tools to be exposed by using the Add Tool
action. Connecting MCP Clients can discover the tools and the model can choose to call them if it helps to solve the user’s requests.
The selected microflow must adhere to the following principles:
- Input needs to be the same as described in the
Schema
attribute (only primitives and/or an object of typeMCPServer.Tool
are supported) - The return value needs to be a
TextContent
object which you can create inside of the microflow to return the relevant information to the model based on the outcome of the microflow.
For an example, see the Example Implementations
folder inside of the module.
Function calling is a highly effective capability and should be used with caution. Tool microflows currently do not run in the context of the authenticated user, and thus cannot apply entity access.
Mendix strongly recommends keeping the user in the loop (such as by using confirmation logic which is integrated into many MCP clients), if the tool microflows have a potential impact on the real world on behalf of the end-user. Examples include sending emails, posting content online, or making purchases. In such cases, evaluate the use cases and implement security measures when exposing these tools to external AI systems via MCP.
Add Prompts
After the Create MCP Server action, you can add one or multiple Prompts to be exposed using the Add Prompt
action. Prompts let servers define reusable prompt templates and workflows and they are a powerful way to standardize and share common LLM interactions. For more information, see Prompt Engineering. Connecting MCP Clients can discover the prompts and make them selectable for users to start or continue a conversation. If your prompt (and microflow) requires any input parameters that the user should pass, you need to use the Populate Prompt Argument List
action for each parameter to describe how the input is used.

The selected microflow needs to apply to the following principles:
- Input should be the same as passed in the
PromptArgument
object (only primitives and/or an object of typeMCPServer.Prompt
are supported) - The return value should be a
PromptMessage
object which you can create inside of the microflow to return the relevant information to the MCP client based on the outcome of the microflow.
Note that, technically, the microflow can include logic beyond simply returning a prompt. However, you should use it with caution, as it might not be clear to users when prompts are used on the client-side.
Technical Reference
The module includes technical reference documentation for the available entities, enumerations, activities, and other items that you can use in your application. You can view the information about each object in context by using the Documentation pane in Studio Pro.
The Documentation pane displays the documentation for the currently selected element. To view it, perform the following steps:
-
In the View menu of Studio Pro, select Documentation.
-
Click the element for which you want to view the documentation.
Read More
- Concept description of Model Context Protocol (MCP)
- The GenAI Showcase App provides an example on how to expose microflows as tools via the MCP Server module.
- The official MCP docs
- The MCP Java SDK GitHub Repository
- A blog post on How to use MCP to bring Mendix Business Logic into Claude for Desktop