diff --git a/content/en/docs/genai/v2/_index.md b/content/en/docs/genai/v2/_index.md index 712191a22fd..34c2ec9b203 100644 --- a/content/en/docs/genai/v2/_index.md +++ b/content/en/docs/genai/v2/_index.md @@ -30,16 +30,16 @@ The following components are available in Agents Kit 2. | App | Description | Latest Released Version | | --- | --- | --- | -| [GenAI Showcase App](https://marketplace.mendix.com/link/component/220475) | Explore example use cases for Agents Kit connectors and modules, including multi-agent patterns, exposing and consuming tools via MCP, interactive chatbots, RAG, function calling, image generation, and semantic search. | 10.3.0 | +| [GenAI Showcase App](https://marketplace.mendix.com/link/component/220475) | Explore example use cases for Agents Kit connectors and modules, including multi-agent patterns, exposing and consuming tools via MCP, interactive chatbots, RAG, function calling, image generation, and semantic search. | 10.6.0 | ### Core Modules {#core-modules} | Module | Description | Latest Released Version | | --- | --- | --- | -| [Agent Commons](/agents/agents-kit-2/reference-guide/agent-commons/) | Build agentic functionality by defining, testing, and evaluating agents at runtime. Iterate on prompts and agent configurations without app redeployment through the integrated Agent Builder UI. | 4.3.1 | -| [Agent Editor](/agents/agents-kit-2/reference-guide/agent-editor/) | Define agents as version-controlled documents in Studio Pro at design time. Author prompts, configure tools and knowledge bases, test locally, and deploy agents as part of your app model. | 2.5.1 | -| [Conversational UI](/agents/agents-kit-2/reference-guide/conversational-ui/) | Create chat interfaces for full-screen, sidebar, or modal GenAI conversations. Monitor token consumption and trace interactions with UI features built on GenAI Commons. | 7.3.1 | -| [GenAI Commons](/agents/agents-kit-2/reference-guide/commons/) | Integrate GenAI connectors with other modules using common capabilities provided by this base module. Required dependency for both core and connector modules. You can also implement your own connector based on this module. | 7.2.0 | +| [Agent Commons](/agents/agents-kit-2/reference-guide/agent-commons/) | Build agentic functionality by defining, testing, and evaluating agents at runtime. Iterate on prompts and agent configurations without app redeployment through the integrated Agent Builder UI. | 4.4.0 | +| [Agent Editor](/agents/agents-kit-2/reference-guide/agent-editor/) | Define agents as version-controlled documents in Studio Pro at design time. Author prompts, configure tools and knowledge bases, test locally, and deploy agents as part of your app model. | 2.6.0 | +| [Conversational UI](/agents/agents-kit-2/reference-guide/conversational-ui/) | Create chat interfaces for full-screen, sidebar, or modal GenAI conversations. Monitor token consumption and trace interactions with UI features built on GenAI Commons. | 7.4.0 | +| [GenAI Commons](/agents/agents-kit-2/reference-guide/commons/) | Integrate GenAI connectors with other modules using common capabilities provided by this base module. Required dependency for both core and connector modules. You can also implement your own connector based on this module. | 7.3.0 | ### Connector Modules {#connectors} @@ -47,19 +47,19 @@ All connectors depend on GenAI Commons and can be used with the other [core modu | Module | Description | Latest Released Version | | --- | --- | --- | -| [Amazon Bedrock Connector](/agents/agents-kit-2/reference-guide/external-connectors/bedrock/) | Connect to Amazon Bedrock. | 11.2.0 | -| [Google Gemini Connector](/agents/agents-kit-2/reference-guide/external-connectors/gemini/) | Connect to Google Gemini. | 2.0.0 | -| [Mendix Cloud GenAI Connector](/agents/agents-kit-2/mx-cloud-genai/mxgenai-connector/) | Connect to Mendix Cloud and use Mendix Cloud GenAI resource packs directly within your Mendix application. | 7.3.0 | -| [Mistral Connector](/agents/agents-kit-2/reference-guide/external-connectors/mistral/) | Connect to Mistral AI. | 2.0.0 | -| [OpenAI Connector](/agents/agents-kit-2/reference-guide/external-connectors/openai/) | Connect to OpenAI and Microsoft Foundry. | 9.3.0 | -| [PgVector Knowledge Base](/agents/agents-kit-2/reference-guide/external-connectors/pgvector/) | Manage and interact with a PostgreSQL PgVector knowledge base. | 7.0.0 | +| [Amazon Bedrock Connector](/agents/agents-kit-2/reference-guide/external-connectors/bedrock/) | Connect to Amazon Bedrock. | 11.3.0 | +| [Google Gemini Connector](/agents/agents-kit-2/reference-guide/external-connectors/gemini/) | Connect to Google Gemini. | 2.2.0 | +| [Mendix Cloud GenAI Connector](/agents/agents-kit-2/mx-cloud-genai/mxgenai-connector/) | Connect to Mendix Cloud and use Mendix Cloud GenAI resource packs directly within your Mendix application. | 7.4.0 | +| [Mistral Connector](/agents/agents-kit-2/reference-guide/external-connectors/mistral/) | Connect to Mistral AI. | 2.2.0 | +| [OpenAI Connector](/agents/agents-kit-2/reference-guide/external-connectors/openai/) | Connect to OpenAI and Microsoft Foundry. | 9.4.0 | +| [PgVector Knowledge Base](/agents/agents-kit-2/reference-guide/external-connectors/pgvector/) | Manage and interact with a PostgreSQL PgVector knowledge base. | 7.1.0 | ### MCP Modules {#mcp-modules} | Module | Description | Latest Released Version | | --- | --- | --- | -| [MCP Client](/agents/agents-kit-2/reference-guide/mcp-modules/mcp-client/) | Access tools and prompts available via MCP inside your Mendix app and add them to LLM requests. | 4.3.0 | -| [MCP Server](/agents/agents-kit-2/reference-guide/mcp-modules/mcp-server/) | Make your Mendix business logic available to any agent in your enterprise landscape. Expose reusable prompts, including the ability to use prompt variables. List and run actions implemented in the application as a tool. | 5.3.0 | +| [MCP Client](/agents/agents-kit-2/reference-guide/mcp-modules/mcp-client/) | Access tools and prompts available via MCP inside your Mendix app and add them to LLM requests. | 4.4.0 | +| [MCP Server](/agents/agents-kit-2/reference-guide/mcp-modules/mcp-server/) | Make your Mendix business logic available to any agent in your enterprise landscape. Expose reusable prompts, including the ability to use prompt variables. List and run actions implemented in the application as a tool. | 5.4.0 | ## Documents in This Section diff --git a/content/en/docs/genai/v2/reference-guide/agent-editor.md b/content/en/docs/genai/v2/reference-guide/agent-editor.md index 4e640ed1a05..e543bef7c37 100644 --- a/content/en/docs/genai/v2/reference-guide/agent-editor.md +++ b/content/en/docs/genai/v2/reference-guide/agent-editor.md @@ -299,7 +299,9 @@ In the published MCP service document, configure the following fields: * **Version**: Enter a version for the MCP service in semantic versioning format. This defaults to `1.0.0`. * **Endpoint**: Enter the path to append to the app URL. External MCP clients use this endpoint to connect to the service. The endpoint path may only contain lowercase letters, numbers, hyphens, underscores, and forward slashes. * **Protocol version**: Select the MCP protocol version that connecting clients must support. This defaults to `v2025_03_26`. -* **Requires authentication**: Select whether MCP clients must be authenticated. Mendix recommends setting up authentication if the Mendix application is reachable outside of your local environment. If set to **No**, the MCP service is accessible to anyone without authentication. When authentication is required, select a microflow that authenticates incoming requests. The microflow input can only be `System.HttpRequest` and/or `MCPServer.MCcperver`, and its output must be `System.User`. Return empty if authentication fails. +* **Requires authentication**: Select whether MCP clients must be authenticated. Mendix recommends setting up authentication if the Mendix application is reachable outside of your local environment. If set to **No**, the MCP service is accessible to anyone without authentication. When authentication is required, select a microflow that authenticates incoming requests. The microflow input can only be `System.HttpRequest` and/or `MCPServer.McpServer`, and its output must be `System.User`. Return empty if authentication fails. +* **Authorization server URL**: Optionally, when authentication is required, enter the issuer URL of the OAuth authorization server where MCP clients obtain access tokens. Your authentication microflow must validate the tokens. For more information, see [Enable OAuth](/agents/agents-kit-2/reference-guide/mcp-modules/mcp-server/#oauth). +* **Scopes**: Optionally, when an authorization server URL is set, enter the scopes that MCP clients should request, separated by spaces. To add tools, click **New** in the **Tools** section and configure the following fields: diff --git a/content/en/docs/genai/v2/reference-guide/mcp-modules/mcp-server.md b/content/en/docs/genai/v2/reference-guide/mcp-modules/mcp-server.md index 1ec484c0bc9..02c4b4a05c2 100644 --- a/content/en/docs/genai/v2/reference-guide/mcp-modules/mcp-server.md +++ b/content/en/docs/genai/v2/reference-guide/mcp-modules/mcp-server.md @@ -78,6 +78,39 @@ Within your microflow, you can implement your custom logic to authenticate the u The `User` returned in the microflow is used for all subsequent prompt and tool microflows within the same session. This makes the `currentUser` and `currentSession` variables available, allowing you to apply entity access for user-based access control based on the default Mendix entity access settings. +If authentication fails, return empty instead of throwing an error. An empty return value results in a `401 Unauthorized` response, while an error results in a `500 Internal Server Error` response. + +#### Enable OAuth {#oauth} + +MCP clients that support [MCP authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization), such as Visual Studio Code can sign in users at an OAuth 2.0 authorization server (identity provider) and send the access token to the MCP Server. To let clients discover where to obtain a token, set the following optional parameters in the `Create MCP Server` action: + +* `AuthorizationServerUrl`: The issuer URL of the authorization server, for example, `https://login.microsoftonline.com//v2.0` for Microsoft Entra ID. This parameter requires an authentication microflow. +* `Scopes`: The OAuth scopes that clients should request when obtaining an access token for this MCP Server. Configure scopes that represent access to the MCP Server or its capabilities, as defined by your authorization server. For example, an authorization server might define a scope such as `mymcp.access`. Do not use OpenID Connect scopes such as `openid` or `email` as required scopes for your MCP server. You must register the scope value (for example, `mymcp.access`) at your IdP, which enables your IdP to make authorization decisions for access to your MCP server. + +When `AuthorizationServerUrl` is set, the MCP Server does the following: + +* It publishes [Protected Resource Metadata (RFC 9728)](https://datatracker.ietf.org/doc/html/rfc9728#name-protected-resource-metadata) at `//.well-known/oauth-protected-resource`. The metadata contains the MCP endpoint as `resource`, the authorization server, the scopes, and the server name. +* It adds a `WWW-Authenticate` header to `401 Unauthorized` responses. The header refers to the metadata URL and includes the scopes. + +The MCP Server module does not validate access tokens itself. Your authentication microflow must do the following for every request: + +1. Read the `Authorization` header from `System.HttpRequest`. If missing, return empty to initiate the client sign-in flow. + +2. Validate the token. Depending on the authorization server, you can do this in one of the following ways: + + * Use the [OIDC SSO](/appstore/modules/oidc/) module, which supports validating tokens against the signing keys of the authorization server. This is required for authorization servers without an introspection endpoint, such as Microsoft Entra ID. For example, use the `DecodeVerifyJWTPlainText` action to verify and get the JWT token to validate further fields, such as, scopes. Note that the `APIAuthentication` action is currently not supported when called from the MCP Server module. + * In exceptional cases where your IdP issues opaque tokens that is not being a JWT or when your IdP supports token revocation, you may want to call the token introspection endpoint [(RFC 7662)](https://datatracker.ietf.org/doc/html/rfc7662#section-2) of the authorization server, for example, with a `Call REST service` activity. In most scenarios this is not needed. Common IdP-technologies such as Entra ID, Okta, Keycloak issue access tokens having the JWT profile. + +3. Check that the token is active and not expired, and that the audience (`aud`) is the value that the authorization server issues for your MCP Server. Otherwise, your MCP Server accepts tokens that were issued for other applications. Based on your requirements, check other fields such as scopes or issuer. + +4. Return the `System.User` that belongs to the token. For example, retrieve the user by name based on the `preferred_username` claim, or create a new user. For more information, see [user classification](/developerportal/deploy/implementing-user-metering/#user-classification). + +{{% alert color="info" %}} +The authentication microflow runs for every request, including several requests when the client connects. If your microflow calls an external service, such as an introspection endpoint, consider the additional response time or implement custom logic for expiry state management. +{{% /alert %}} + +The MCP client must be registered at the authorization server to obtain an access token. Typically, you register the client manually in your IdP's admin pages. + #### 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 latest version of the MCP Server module only supports `v2025-03-26` and the Streamable HTTP transport. MCP clients that need to connect to a Mendix MCP server must support the same version. Note that Mendix follows the offered capabilities of the MCP Java SDK. @@ -138,6 +171,22 @@ Remove-Item -Path "$env:LocalAppData\npm-cache\_npx" -Recurse -Force npm cache clean --force ``` +### MCP Client Does Not Start the OAuth Sign-In + +If the client receives a `401 Unauthorized` response but does not start the sign-in flow, check the following: + +* `AuthorizationServerUrl` is set and the MCP server was restarted afterward. The metadata URL `//.well-known/oauth-protected-resource` must return the authorization server. +* The authentication microflow returns empty instead of throwing an error when no valid token is sent. +* The client configuration does not contain a fixed `Authorization` header, which would be sent instead of the OAuth token. + +### Authorization Server Rejects the Sign-In + +If the authorization server reports invalid scopes, set the `Scopes` parameter of the `Create MCP Server` action, so that the client only requests these scopes. Make sure that the scopes are assigned to the client at the authorization server. + +### Microsoft Entra ID Error AADSTS9010010 {#entra-id} + +If Microsoft Entra ID rejects the request with error `AADSTS9010010: the resource parameter provided in the request doesn't match with the requested scopes.`, then the `resource` parameter ([RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707#name-resource-parameter)) does not match the Application ID URI of the scope. To avoid this, set in the Azure portal the Application ID URI to the MCP endpoint, for example, `https://mymendixapp.com//mcp`. This requires that the domain of your app is a verified domain in your tenant. + ### Conflicted Lib Error After Module Import If you encounter an error caused by conflicting Java libraries, such as `java.lang.NoSuchMethodError: 'com.fasterxml.jackson.annotation.OptBoolean com.fasterxml.jackson.annotation.JsonProperty.isRequired()'`, try synchronizing all dependencies (**App** > **Synchronize dependencies**) and then restart your application.