Merge pull request mendix#9738 from liamsommer-mx/new-mcp-server

SAS-1277: added documentation for MCP and MCP Server

Author: Karuna-Mendix

content/en/docs/marketplace/genai/concepts/model-context-protocol.md

@@ -0,0 +1,59 @@
+---
+title: "Model Context Protocol (MCP)"
+url: /appstore/modules/genai/mcp/
+linktitle: "Model Context Protocol (MCP)"
+weight: 50
+description: "This document describes the Model Context Protocol (MCP) and how it is used in Mendix."
+---
+
+## Introduction
+
+The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol that standardizes how Large Language Models (LLMs) can autonomously connect to apps. Many AI platforms and third-party systems have already adopted MCP for easier integration and empowerment of LLMs. Mendix provides an [MCP Server](/appstore/modules/genai/genai-for-mx/mcp-server/) module to facilitate a MCP server from a Mendix app, enabling developers to expose tools and prompts to external MCP clients.
+
+{{< figure src="/attachments/appstore/platform-supported-content/modules/genai/mcpserver/mcp-client-server-architecture.jpg" >}}
+
+As described in the diagram above, a user can chat with a model in the MCP Host application (for example, Claude Desktop), which connects to the MCP Server (a Mendix app) via MCP to discover available tools and prompts. If the user's request can be solved with any available tool, the LLM can call a tool which is executed in the Mendix app and returns the result. This approach allows developers to integrate their Mendix app with existing external AI systems.
+
+MCP provides a vendor-agnostic approach to integrate third-party services with LLM interaction to enrich its context beyond training data and the current chat conversation. In Mendix, this enables developers to build microflows which can be exposed as tools to external AI tools and thus creating powerful AI-agentic systems using low-code.
+
+## Terminology
+
+To understand the basics of MCP, it is important to know the common terminology.
+
+### MCP Host
+
+The MCP host is typically the application that facilitates interaction with LLMs. While a chat interface is the most common use case, the host can support a variety of interaction use cases. The host takes care of the communication between users and models, while enabling users to manage their AI use, for example, managing credentials or historical chat conversations.
+
+### MCP Client
+
+The MCP client usually runs inside of the MCP Host and is responsible of connecting to one MCP server outside of the MCP host application. The client follows the MCP principles and should technically be able to connect to any MCP server. A host can maintain multiple clients at the same time and thus connecting to multiple MCP servers.
+
+### MCP Server
+
+MCP server exposes resources that can be discovered by MCP clients and made available to both the model and the user during a chat interaction. Once a request is made, the server processes it using its built-in logic and returns a value for the MCP host to use.
+
+Servers can expose the following three main types of resources:
+
+#### Tools
+
+The most common type of resource is tool, which exposes executable functionality such as microflows to clients. Those can not only contain simple retrieve logic to get information from a database, but also perform actions on behalf of the user, for example, submitting a report or changing values. Typically, a model in the MCP host chooses when to call a tool based on the context of the chat.
+
+#### Prompts
+
+Prompts can be exposed to define templates and to structure interactions between the user and the model, for example, by allowing specific input fields that fill placeholders. In Mendix MCP servers, prompts work similarly to tools, as they also execute a microflow. Both end-users and LLMs choose when to use a prompt based on the prompt's definition.
+
+#### Resources
+
+In general, generic resources, such as files or database records, can be exposed via MCP. There are no guidelines on how to use resources on the client side; for example, if a user first needs to add them to a chat or if they are automatically incorporated to the chat context. Currently, Mendix does not support resources to be exposed.
+
+## MCP Example in the GenAI Showcase App
+
+An example for setting up an MCP server is available in the [GenAI Showcase App](https://marketplace.mendix.com/link/component/220475). The app guides you through available tools and prompts that will be exposed when the server is started. Additionally, it shows an example for setting up authentication using username and password. Claude Desktop is used as an example MCP host to demonstrate the client-server communication. However, other MCP hosts, such as GitHub Copilot, can also be used.
+
+## Read More
+
+* The [MCP Server module](/appstore/modules/genai/genai-for-mx/mcp-server/)
+* The [GenAI Showcase App](https://marketplace.mendix.com/link/component/220475) provides an example on how to expose microflows as tools via the MCP Server module. 
+* The official [MCP docs](https://modelcontextprotocol.io/introduction)
+* The [MCP Java SDK GitHub Repository](https://github.com/modelcontextprotocol/java-sdk)
+* A blog post on [How to use MCP to bring Mendix Business Logic into Claude for Desktop](https://www.mendix.com/blog/how-to-use-mcp-to-bring-mendix-business-logic-into-claude-for-desktop/)

content/en/docs/marketplace/genai/how-to/_index.md

@@ -40,6 +40,7 @@ Generative Artificial Intelligence (GenAI) transforms business applications, emp
 * The [Mendix Cloud GenAI Resource Packs](/appstore/modules/genai/mx-cloud-genai/resource-packs/) to learn how to quickly access GenAI capabilities from a Mendix app.
 * The [OpenAI](/appstore/modules/genai/openai/) provides essential information about the OpenAI connector.
 * The [Amazon Bedrock](/appstore/modules/aws/amazon-bedrock/) provides key information about the AWS Bedrock connector.
+* The [MCP Server Module](/appstore/modules/genai/genai-for-mx/mcp-server/) provides reusable operations to create and initialize an MCP server within a Mendix app to expose tools and prompts to external clients.
 * The [PGVector Knowledge Base](/appstore/modules/genai/pgvector/) offers the option for a private knowledge base outside of the LLM infrastructure.
 
 For any additional feedback, send a message in the [#genai-connectors](https://mendixcommunity.slack.com/archives/C07P8NRBLN9) channel on the Mendix Community Slack. You can sign up for the Mendix Community [here](https://mendixcommunity.slack.com/join/shared_invite/zt-270ys3pwi-kgWhJUwWrKMEMuQln4bqrQ#/shared-invite/email).

content/en/docs/marketplace/genai/reference-guide/_index.md

@@ -2,7 +2,7 @@
 title: "Reference Guide"
 url: /appstore/modules/genai/reference-guide/
 linktitle: "Reference Guide"
-weight: 40
+weight: 20
 description: "Provides references of Mendix's GenAI Modules and Tools."
 no_list: false
 ---

content/en/docs/marketplace/genai/reference-guide/mcp-server.md

@@ -0,0 +1,108 @@
+---
+title: "MCP Server"
+url: /appstore/modules/genai/genai-for-mx/mcp-server/
+linktitle: "MCP Server"
+description: "This document describes the purpose, configuration, and usage of the MCP Server module from the Mendix Marketplace that allows developers to expose Mendix logic to external MCP clients and AI systems."
+weight: 20
+---
+
+## Introduction
+
+The [MCP Server](https://marketplace.mendix.com/link/component/240380) module provides easy low-code capability to set up MCP ([Model Context Protocol](/appstore/modules/genai/mcp/)) 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](https://github.com/modelcontextprotocol/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](/appstore/modules/genai/function-calling/).
+
+### Limitations {#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](https://marketplace.mendix.com/link/component/227934) 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](/appstore/use-content/) to install the [MCP Server](https://marketplace.mendix.com/link/component/240380) module from the Marketplace.
+
+## Configuration
+
+### Create MCP Server {#create-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](#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](https://marketplace.mendix.com/link/component/220475), 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/or `System.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](https://modelcontextprotocol.io/specification/2025-03-26/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](#create-server) action, you can add one or multiple microflows as [Tools](https://modelcontextprotocol.io/docs/concepts/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 type `MCPServer.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.
+
+{{% alert color="warning" %}}
+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.
+{{% /alert %}}
+
+### Add Prompts
+
+After the [Create MCP Server](#create-server) action, you can add one or multiple [Prompts](https://modelcontextprotocol.io/docs/concepts/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](/appstore/modules/genai/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.
+
+{{< figure src="/attachments/appstore/platform-supported-content/modules/genai/mcpserver/mcp_addprompt_example.png" >}}
+
+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 type `MCPServer.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:
+
+1. In the [View menu](/refguide/view-menu/) of Studio Pro, select **Documentation**.
+2. Click the element for which you want to view the documentation.
+
+    {{< figure src="/attachments/appstore/platform-supported-content/modules/technical-reference/doc-pane.png" >}}
+
+## Read More
+
+* Concept description of [Model Context Protocol (MCP)](/appstore/modules/genai/mcp/)
+* The [GenAI Showcase App](https://marketplace.mendix.com/link/component/220475) provides an example on how to expose microflows as tools via the MCP Server module. 
+* The official [MCP docs](https://modelcontextprotocol.io/introduction)
+* The [MCP Java SDK GitHub Repository](https://github.com/modelcontextprotocol/java-sdk)
+* A blog post on [How to use MCP to bring Mendix Business Logic into Claude for Desktop](https://www.mendix.com/blog/how-to-use-mcp-to-bring-mendix-business-logic-into-claude-for-desktop/)