Language review: MCP server doc

Karuna-Mendix · Karuna-Mendix · commit fc69694f0a07 · 2025-07-04T12:24:44.000+05:30
diff --git a/content/en/docs/marketplace/genai/reference-guide/mcp-server.md b/content/en/docs/marketplace/genai/reference-guide/mcp-server.md
@@ -23,7 +23,7 @@ The current version has the following limitations:
 * 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 thus (breaking) changes might be introduced with later versions. The open-source protocol as well as the Java SDK are still evolving and regularly updated which also affects this module.
+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
 
@@ -35,33 +35,35 @@ If you start from a blank app, or have an existing project, you must install the
 
 ### 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, which means that this value needs to be known to the the MCP Client (usually set in a configuration file). After the action gets triggered, the server is available for external clients to connect to. As mentioned in the (limitations)[#limitations], the connection is only kept alive for 15 minutes.
+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 scheduled events).
+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.
+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 don't want to enable authentication. There also 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. 
+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 everytime a request is processed for the MCP Server. 
+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 needs to apply to the following principles:
-* Input can only be of type `MCPServer` and/or `System.HttpRequest` to extract required values, such as HttpHeaders from the request.
+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. Please note, that the example authenication miroflow within the module only implements the most basic authentication.
+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 thus 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.
+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 needs to apply to the following principles:
+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.
 
@@ -70,21 +72,21 @@ 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 also strongly advises that you keep the user in the loop (e.g., with user confirmation logic which is integrated into many MCP clients) if tool microflows have a potential impact on the world on behalf of the end-user. Some examples of such microflows include sending an email, posting online, or making a purchase. You should especially evaluate the use case and security when exposing those to external AI systems via MCP.
+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 are hence a powerful way to standardize and share common LLM interactions. You can also read more about prompts and prompt engineering with Mendix [here](https://docs.mendix.com/appstore/modules/genai/prompt-engineering). Connecting MCP Clients can discover the prompts and make them selectable for users to start/continue a conversation. If your prompt (and thus 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:
+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 needs to be the same as passed in the `PromptArgument` object(s) (only primitives and/or an object of type `MCPServer.Prompt` are supported)
-* The return value needs to 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.
 
-Be aware that technically other logic than just returning a prompt can be executed inside of the microflow, which should be used with caution because it might not be clear for users when the prompts are used on the client-side.
+* 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
 
@@ -101,7 +103,6 @@ The **Documentation** pane displays the documentation for the currently selected
 
 * 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 offical [MCP docs](https://modelcontextprotocol.io/introduction)
-* The [MCP Java SDK Github Repository](https://github.com/modelcontextprotocol/java-sdk)
-* Our 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/)
-   
+* 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/)
