Merge pull request #10610 from liamsommer-mx/mcp-server-transport

SAS-1696: updated MCP Server and GenAI Commons; updated model support…

Author: Karuna-Mendix

content/en/docs/marketplace/genai/_index.md

@@ -71,9 +71,9 @@ Mendix connectors offer direct support for the following models:
 
 | Architecture | Models | Category | Input | Output | Additional capabilities |
 | -------------- | --------------------- | --------------------- | ------------------- | ----------- | ----------------------- |
-| Mendix Cloud GenAI | Anthropic Claude 3.5 Sonnet, Anthropic Claude 3.7 Sonnet, Anthropic Claude 4.0 Sonnet | Chat Completions | text, image, document | text | Function calling |
-| | Cohere Embed English, Cohere Embed Multilingual | Embeddings | text | embeddings | |
-| Azure / OpenAI | gpt-4, gpt-4-turbo, gpt-4o, gpt-4o mini, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-5.0, gpt-5.0-mini, gpt-5.0-nano | Chat completions | text, image, document (OpenAI only) | text | Function calling |
+| Mendix Cloud GenAI | Anthropic Claude 3.5 Sonnet, Anthropic Claude 3.7 Sonnet, Anthropic Claude 4.0 Sonnet, Anthropic Claude 4.5 Sonnet | Chat Completions | text, image, document | text | Function calling |
+| | Cohere Embed v3 English and multilangual, Cohere Embed v4 | Embeddings | text | embeddings | |
+| Azure / OpenAI | gpt-4, gpt-4-turbo, gpt-4o, gpt-4o mini, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-5.0, gpt-5.0-mini, gpt-5.0-nano, gpt-5.1, gpt-5.2, o1, o1-mini, o3, o3-mini, o4-mini | Chat completions | text, image, document (OpenAI only) | text | Function calling |
 | | DALL·E 2, DALL·E 3, gpt-image-1 | Image generation | text | image | |
 | | text-embedding-ada-002, text-embedding-3-small, text-embedding-3-large | Embeddings | text | embeddings | |
 | Mistral | Mistral Large 3, Mistral Medium 3.1, Mistral Small 3.2, Ministral 3 (3B, 8B, 14B), Magistral (Small, Medium) | Chat Completions | text, image | text | Function calling |
@@ -85,8 +85,7 @@ Mendix connectors offer direct support for the following models:
 | | Amazon Nova Pro, Amazon Nova Lite | Chat Completions | text, image, document | text | Function calling |
 | | Amazon Titan Image Generator G1 | Image generation | text | image | |
 | | Amazon Titan Embeddings Text v2 | Embeddings | text | embeddings | |
-| | Anthropic Claude 2.0, Anthropic Claude 2.1 | Chat Completions | text, document | text | |
-| | Anthropic Claude 3 Sonnet, Anthropic Claude 3.5 Sonnet, Anthropic Claude 3.5 Sonnet v2, Anthropic Claude 3 Haiku, Anthropic Claude 3 Opus, Anthropic Claude 3.5 Haiku, Anthropic Claude 3.7 Sonnet, Anthropic Claude 4 Sonnet | Chat Completions | text, image, document | text | Function calling |
+| | Anthropic Claude 3 Sonnet, Anthropic Claude 3.5 Sonnet, Anthropic Claude 3.5 Sonnet v2, Anthropic Claude 3 Haiku, Anthropic Claude 3 Opus, Anthropic Claude 3.5 Haiku, Anthropic Claude 3.7 Sonnet, Anthropic Claude 4.5 Sonnet, Anthropic Claude 4.5 Haiku, Anthropic Claude 4.5 Opus | Chat Completions | text, image, document | text | Function calling |
 | | Cohere Command | Chat Completions | text, document | text | |
 | | Cohere Command Light | Chat Completions | text | text | |
 | | Cohere Command R, Cohere Command R+ | Chat Completions | text, document | text | Function calling |

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

@@ -265,6 +265,7 @@ A tool in the tool collection. This is sent along with the request to expose a l
 | `ToolType` | The type of the tool. Refer to the documentation supplied by your AI provider for information about the supported types. |
 | `Microflow` | The name (string) of the microflow that this tool represents. |
 | `MCPServerName` | The name of the MCP server (only appliable for MCP Tools). |
+| `Schema` | The schema represents the raw JSON schema defined by the tool. This is typically the case when the tool is external and not a Mendix microflow. |
 
 #### `Function` {#function}
 
@@ -283,24 +284,6 @@ A tool of the type *function*. This is a specialization of [Tool](#tool) and rep
 | `MinimumSimilarity` | Specifies the minimum similarity score (usually 0-1) of the passed chunk and the knowledge chunks in the knowledge base. |
 | `MaxNumberOfResults` | Specifies the maximum number of results that should be retrieved from the knowledge base. |
 
-#### `ArgumentInput` {#argument-input}
-
-For tools which are not executed in the same Mendix application, but still registered with the request and called from the application, `ArgumentInput` objects are added to the [Tool](#tool). When the tool is called, the arguments are not passed directly to the microflow, but can be extracted from the [Argument](#argument) of the [ToolCall](#toolcall).
-
-| Attribute | Description |
-| --- | --- |
-| `Name` | Name of the argument. |
-| `_Type` | Data type of the argument, for example, string, number, boolean, enum. |
-| `Required` | Indicates if the argument is required for calling the tool. |
-
-#### `EnumValue` {#enum-value}
-
-The `EnumValue` specifies available keys for "enum" [ArgumentInput](#argument-input) data types, so that the model is restricted to use valid input.
-
-| Attribute | Description |
-| --- | --- |
-| `Key` | Key of an enumeration. |
-
 #### `StopSequence` {#stopsequence}
 
 For many models, `StopSequence` can pass a list of character sequences (for example a word) along with the request. The model will stop generating content when a word of that list occurs next.
@@ -332,6 +315,7 @@ A tool call object may be generated by the model in certain scenarios, such as a
 | `Name` | The name of the tool to call. This refers to the `Name` attribute of one of the [Tools](#tool) in the Request. |
 | `ToolType` | The type of the tool. View AI provider documentation for supported types. |
 | `ToolCallId` | This is a model-generated ID of the proposed tool call. It is used by the model to map an assistant message containing a tool call with the output of the tool call (tool message). |
+| `Input` | The input is the raw tool JSON input generated by the model, usually passed for external tools where no mapping to a microflow is required. |
 
 #### `Argument` {#argument}
 

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

@@ -65,7 +65,7 @@ For both actions, you can pass an `ArgumentCollection` if the prompt or tool req
 
 ### Using MCP Client Module with GenAI Commons and Conversational UI {#use-with-genai-commons}
 
-To add all tools from an MCP server to a `GenAICommons.Request`, you can use the `Request: Add all tools from MCP server` toolbox action. This action will first list all tools from the provided MCP server configuration, iterate over them, and adding them one by one to the tool collection. The request can then be passed to a Chat Completions operation.
+To add all tools from an MCP server to a `GenAICommons.Request`, you can use the `Request: Add all tools from MCP server` toolbox action. This action will first list all tools from the provided MCP server configuration, iterate over them, and adding them one by one to the tool collection. The request can then be passed to a Chat Completions operation. 
 
 You can also find an example [action microflow](/appstore/modules/genai/genai-for-mx/conversational-ui/#action-microflow) `ChatCompletions_MCPClient_ActionMicroflow` in the **Example Implementations** folder of the module. This microflow demonstrates how a Conversational UI chat action including MCP tools can be facilitated. Duplicate and include this microflow into your custom module and modify it according to your requirements.
 

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

@@ -24,9 +24,10 @@ The current version has the following limitations:
 * Tools can only return String values, either directly as String type or using the `TextContent` entity.
 * Prompts can only return a single message.
 * Running an MCP Server is currently only supported on single-instance environments.
-* The tool fails to return responses with large payloads to the client successfully. This issue is currently under investigation.
 
+{{% alert color="info" %}}
 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.
+{{% /alert %}}
 
 ## Installation
 
@@ -38,7 +39,7 @@ If you start from a standard Mendix blank app, or have an existing project, you
 
 ### 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.
+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. Note that the path cannot be `mcp` and cannot end on `/mcp`, because those are reserved endpoints. 
 
 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.
 
@@ -61,15 +62,19 @@ The `User` returned in the microflow is used for all subsequent prompt and tool
 
 #### 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.
+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 latest version of the MCP Server module currently only supports `v2025-03-26` and the Streamable HTTP 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.
+
+{{% alert color="info" %}}
+Since version 4.0.0 of the module, the protocol version `v2024-11-05` was replaced by `v2025-03-26`, which changed the transport from HTTP + SSE to Streamable HTTP because HTTP + SSE is officially deprecated. Most clients already support the new transport, such as the Mendix [MCP Client](/appstore/modules/genai/mcp-modules/mcp-client/) module.
+{{% /alert %}}
 
 ### 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). If no Schema is passed in the `Add tool` action, it will be automatically created based on the microflow's input parameters.
+* Input needs to be the same as described in the `Schema` attribute (only primitives and/or an object of type `MCPServer.Tool` are supported). If no Schema is passed in the `Add tool` action, it will be automatically created based on the microflow's input parameters, by setting all of them as required.
 * The return value must be either of type `String` or `TextContent`. You can create a `TextContent` object within 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.