From d3f28fd6203ac88007e545efa8a9a87a21d86978 Mon Sep 17 00:00:00 2001 From: nidhi251289 Date: Wed, 1 Jul 2026 16:31:21 +0200 Subject: [PATCH 1/2] New MCP doc for Private cloud APIs --- .../private-cloud/private-cloud-api-mcp.md | 194 ++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 content/en/docs/deployment/private-cloud/private-cloud-api-mcp.md diff --git a/content/en/docs/deployment/private-cloud/private-cloud-api-mcp.md b/content/en/docs/deployment/private-cloud/private-cloud-api-mcp.md new file mode 100644 index 00000000000..78fba0470c5 --- /dev/null +++ b/content/en/docs/deployment/private-cloud/private-cloud-api-mcp.md @@ -0,0 +1,194 @@ +--- +title: "Using Mendix on K8s Deploy and Build APIs with AI Agents (MCP)" +url: /developerportal/deploy/deploy-mxonk8s-apis-with-ai-agents/ +description: "Describes how to connect AI coding assistants to Mendix on Kubernetes using the Model Context Protocol (MCP), enabling AI agents to manage deployments, environments, and app lifecycle through natural language." +weight: 100 +--- + +## Introduction + +[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) enables AI coding assistants to connect to Mendix on Kubernetes environments. Once connected, an AI assistant can manage deployments, environments, and the application lifecycle through natural language. + +For example, you can ask the AI assistant to list your apps, deploy the latest package to an acceptance environment, or stop a production environment, without writing `curl` commands or navigating the Mendix on Kubernetes Portal. + +{{% alert color="warning" %}} +The use of AI tools is non-deterministic, outputs may vary between runs. AI Assistants/Agents will have permissions based on what the Personal Access Token (PAT) have access to. Carefully review and limit the scope of credentials before use. +{{% /alert %}} + +## Prerequisites + +Before you start, make sure you have the following: + +* An MCP-compatible AI client that supports custom request headers, such as Claude Code or VS Code with GitHub Copilot +* A Mendix account with API access enabled +* A [Personal Access Token (PAT)](/portal/user-settings/#pat) with the `mx:deployment:write` and `mx:deployment:read` scopes selected for [Deploy APIs](https://docs.mendix.com/apidocs-mxsdk/apidocs/private-cloud-deploy-api/) +* A [Personal Access Token (PAT)](/portal/user-settings/#pat) with the `mx:privatecloud-build:read`, `mx:privatecloud-build:write` and `mx:modelrepository:write` scopes selected for [Build APIs](https://docs.mendix.com/apidocs-mxsdk/apidocs/private-cloud-build-api/) + +## Connecting Your AI Assistant {#connecting} + +### Claude Code {#claude-code} + +To add the Mendix MCP server in Claude Code, run the following command in your terminal: + +```bash +claude mcp add --scope user --transport http mendix-cloud-mcp-private \ +https://mcp.home.mendix.com/private \ +--header "Authorization: MxToken {GENERATED_PAT}" +``` + +Replace the following placeholders with your credentials: + +* `{GENERATED_PAT}` – the generated Mendix Personal Access Token (PAT) + + +To verify the connection, run the following command: + +```bash +claude mcp get mendix-cloud-mcp-private +``` + +A successful connection displays output similar to the following: + +```bash +claude mcp get mendix-cloud-mcp-private +mendix-cloud-mcp-private: + Scope: User config (available in all your projects) + Status: ✔ Connected + Type: http + URL: https://mcp.home.mendix.com/private + Headers: + Authorization: MxToken {GENERATED_PAT} + +To remove this server, run: claude mcp remove mendix-cloud-mcp -s user +``` + +### VS Code with GitHub Copilot {#vs-code} + +To add the Mendix on Kubernetes MCP server in VS Code, add the following configuration to your `.vscode/settings.json` file or your VS Code user settings: + +```json +{ + "mcp":{ + "servers":{ + "mendix-cloud-mcp-private":{ + "type":"http", + "url":"https://mcp.home.mendix.com/private", + "headers":{ + "Authorization":"MxToken {GENERATED_PAT}" + } + } + } + } +} +``` + +Replace the placeholder values with your credentials as described in the [Claude Code](#claude-code) section above. + +## Available Capabilities {#capabilities} + +Once connected, your AI assistant has access to the following capabilities. + +### Apps and Environments + +| Action | Example Prompt | +| --- | --- | +| Get namespace manifest | `mx:deployment:read` or `mx:deployment:write` | +| Get namespaces manifest | `mx:deployment:read` or `mx:deployment:write` | +| Get cluster manifest | `mx:deployment:read` or `mx:deployment:write` | +| Get clusters manifest | `mx:deployment:read` or `mx:deployment:write` | +| Create cluster | `mx:deployment:write` | +| Update cluster | `mx:deployment:write` | +| Delete cluster | `mx:deployment:write` | +| Create namespace | `mx:deployment:write` | +| Update namespace | `mx:deployment:write` | +| Delete namespace | `mx:deployment:write` | +| Get environment manifest | `mx:deployment:read` or `mx:deployment:write` | +| Get multiple environment manifest| `mx:deployment:read` or `mx:deployment:write` | +| Create environment | `mx:deployment:write` | +| Update environment | `mx:deployment:write` | +| Delete environment | `mx:deployment:write` | +| Get apps manifest | `mx:deployment:write` and `mx:app:metadata:read` | +| Get app manifest | `mx:deployment:write` and `mx:app:metadata:read` | +| Get job | `mx:deployment:read` and `mx:deployment:write` | + + +### Deployments and Packages + +| Action | Example Prompt | +| --- | --- | +| Build deployment package | `mx:privatecloud-build:write` and `mx:modelrepository:write` | +| Upload deployment package | `mx:privatecloud-build:write` | +| Delete deployment package | `mx:privatecloud-build:write` | +| Get deployment package | `mx:privatecloud-build:read` or `mx:privatecloud-build:write` | +| Get deployment package list | `mx:privatecloud-build:read` or `mx:privatecloud-build:write` | +| Get Job | `mx:privatecloud-build:read` or `mx:privatecloud-build:write` | + +## Authentication {#authentication} + +Your credentials are passed directly to the Mendix on Kubernetes APIs and are not stored or inspected by the MCP gateway. Each user authenticates using their own credentials. + +Two authentication methods are used depending on the API: + +| API Version | Headers Required | +| --- | --- | +| Deploy API v4, App Permissions | `Authorization: MxToken {GENERATED_PAT}` | + +{{% alert color="info" %}} +Include all three headers in your connection configuration to ensure all tools work correctly. +{{% /alert %}} + + +## Client Compatibility {#compatibility} + +The Mendix on Kubernetes MCP integration works with any MCP-compatible client that supports HTTP transport (streamable HTTP) and custom headers for authentication. + +{{% alert color="warning" %}} +Clients that only support OAuth 2.0 authentication without custom header support are not compatible with the Mendix Cloud MCP integration, as Mendix APIs use PAT token. +{{% /alert %}} + +## Known Limitations {#limitations} + +The following limitations apply: + +| Limitation | Details | +| --- | --- | +| File uploads not supported | The MCP gateway does not support `application/octet-stream` content types. APIs that require binary file upload, such as uploading a deployment package, are not supported. Use the Mendix Portal or the Mendix CLI instead. | +| Rate limiting | Requests are limited to 60 per minute. High-volume automated workflows may exceed this limit. | +| OAuth-only clients | Clients that exclusively use OAuth 2.0 for MCP authentication cannot connect. | + +## Troubleshooting {#troubleshooting} + +### Connection Fails or Times Out + +* Make sure the URL is exactly `https://mcp.home.mendix.com/private` +* Verify that your JSON configuration uses `"type": "http"` and not `"transport": "http"`. + +### 401 Unauthorized + +Your credentials are incorrect or have expired. Regenerate your PAT and verify that your API key is still active. + +### 403 Forbidden + +You do not have permission to the requested resource. Verify that you have the correct role for the app or environment you are accessing. For more information, refer to [Node Permissions](/developerportal/deploy/node-permissions/). + +### 406 Not Acceptable + +Your MCP client is not sending the correct `Accept` header. This happens when you hand-edit the JSON configuration and use `"transport": "http"` instead of `"type": "http"` as the key. To fix this, remove and re-add the connection using the CLI, which sets the correct configuration automatically: + +```bash +claude mcp remove mendix-cloud-mcp-private +claude mcp add --scope user --transport http mendix-cloud-mcp \ +https://mcp.home.mendix.com/private \ +--header "Authorization: MxToken {GENERATED_PAT}" \ +--header "Mendix-Username: {Mendix-Username}" \ +``` + +### Tools Not Showing Up + +* Wait 10–15 seconds after connecting for tool discovery to complete. +* Run `claude mcp get mendix-cloud-mcp-private` to check the connection status. +* If the status shows an error, remove and re-add the connection. + +## Feedback + +To report an issue or request additional API coverage, contact your Mendix CSM.Nidhi \ No newline at end of file From e065ad2999f6a5a902e2c31168dddb5ada1fe6f1 Mon Sep 17 00:00:00 2001 From: katarzyna-koltun-mx <108737161+katarzyna-koltun-mx@users.noreply.github.com> Date: Wed, 22 Jul 2026 12:52:26 +0200 Subject: [PATCH 2/2] Update private-cloud-api-mcp.md --- .../private-cloud/private-cloud-api-mcp.md | 86 +++++++++++-------- 1 file changed, 52 insertions(+), 34 deletions(-) diff --git a/content/en/docs/deployment/private-cloud/private-cloud-api-mcp.md b/content/en/docs/deployment/private-cloud/private-cloud-api-mcp.md index 78fba0470c5..94957fc54b8 100644 --- a/content/en/docs/deployment/private-cloud/private-cloud-api-mcp.md +++ b/content/en/docs/deployment/private-cloud/private-cloud-api-mcp.md @@ -12,7 +12,7 @@ weight: 100 For example, you can ask the AI assistant to list your apps, deploy the latest package to an acceptance environment, or stop a production environment, without writing `curl` commands or navigating the Mendix on Kubernetes Portal. {{% alert color="warning" %}} -The use of AI tools is non-deterministic, outputs may vary between runs. AI Assistants/Agents will have permissions based on what the Personal Access Token (PAT) have access to. Carefully review and limit the scope of credentials before use. +The use of AI tools is non-deterministic, outputs may vary between runs. AI assistants (agents) are assigned permissions based on the access rights of the Personal Access Token (PAT). Carefully review and limit the scope of credentials before use. {{% /alert %}} ## Prerequisites @@ -26,45 +26,54 @@ Before you start, make sure you have the following: ## Connecting Your AI Assistant {#connecting} +Refer to the following sections for information about connecting your agent. + ### Claude Code {#claude-code} -To add the Mendix MCP server in Claude Code, run the following command in your terminal: +To add the Mendix MCP server in Claude Code, perform the following steps: -```bash -claude mcp add --scope user --transport http mendix-cloud-mcp-private \ -https://mcp.home.mendix.com/private \ ---header "Authorization: MxToken {GENERATED_PAT}" -``` +1. Run the following command in your terminal: -Replace the following placeholders with your credentials: + ```bash + claude mcp add --scope user --transport http mendix-cloud-mcp-private \ + https://mcp.home.mendix.com/private \ + --header "Authorization: MxToken {GENERATED_PAT}" + ``` -* `{GENERATED_PAT}` – the generated Mendix Personal Access Token (PAT) +2. Replace the following placeholders with your credentials: + * `{GENERATED_PAT}` - Replace with the generated Mendix Personal Access Token (PAT) -To verify the connection, run the following command: +3. Verify the connection by running the following command: -```bash -claude mcp get mendix-cloud-mcp-private -``` + ```bash + claude mcp get mendix-cloud-mcp-private + ``` + + A successful connection displays output similar to the following: -A successful connection displays output similar to the following: + ```bash + claude mcp get mendix-cloud-mcp-private + mendix-cloud-mcp-private: + Scope: User config (available in all your projects) + Status: ✔ Connected + Type: http + URL: https://mcp.home.mendix.com/private + Headers: + Authorization: MxToken {GENERATED_PAT} + ``` + +4. To remove this server, run the following command: ```bash -claude mcp get mendix-cloud-mcp-private -mendix-cloud-mcp-private: - Scope: User config (available in all your projects) - Status: ✔ Connected - Type: http - URL: https://mcp.home.mendix.com/private - Headers: - Authorization: MxToken {GENERATED_PAT} - -To remove this server, run: claude mcp remove mendix-cloud-mcp -s user +claude mcp remove mendix-cloud-mcp -s user ``` ### VS Code with GitHub Copilot {#vs-code} -To add the Mendix on Kubernetes MCP server in VS Code, add the following configuration to your `.vscode/settings.json` file or your VS Code user settings: +To add the Mendix on Kubernetes MCP server in VS Code, perform the following steps: + +1. Add the following configuration to your `.vscode/settings.json` file or your VS Code user settings: ```json { @@ -82,7 +91,7 @@ To add the Mendix on Kubernetes MCP server in VS Code, add the following configu } ``` -Replace the placeholder values with your credentials as described in the [Claude Code](#claude-code) section above. +2. Replace the placeholder values with your credentials as described in the [Claude Code](#claude-code) section above. ## Available Capabilities {#capabilities} @@ -137,7 +146,6 @@ Two authentication methods are used depending on the API: Include all three headers in your connection configuration to ensure all tools work correctly. {{% /alert %}} - ## Client Compatibility {#compatibility} The Mendix on Kubernetes MCP integration works with any MCP-compatible client that supports HTTP transport (streamable HTTP) and custom headers for authentication. @@ -150,17 +158,25 @@ Clients that only support OAuth 2.0 authentication without custom header support The following limitations apply: -| Limitation | Details | -| --- | --- | -| File uploads not supported | The MCP gateway does not support `application/octet-stream` content types. APIs that require binary file upload, such as uploading a deployment package, are not supported. Use the Mendix Portal or the Mendix CLI instead. | -| Rate limiting | Requests are limited to 60 per minute. High-volume automated workflows may exceed this limit. | -| OAuth-only clients | Clients that exclusively use OAuth 2.0 for MCP authentication cannot connect. | +### File Uploads Not Supported + +The MCP gateway does not support `application/octet-stream` content types. APIs that require binary file upload, such as uploading a deployment package, are not supported. Use the Mendix Portal or the Mendix CLI instead. + +### Rate Limiting + +Requests are limited to 60 per minute. High-volume automated workflows may exceed this limit. + +### OAuth-only Clients + +Clients that exclusively use OAuth 2.0 for MCP authentication cannot connect. ## Troubleshooting {#troubleshooting} ### Connection Fails or Times Out -* Make sure the URL is exactly `https://mcp.home.mendix.com/private` +In case of connection failures or time outs, verify the following: + +* Make sure the URL is exactly `https://mcp.home.mendix.com/private. * Verify that your JSON configuration uses `"type": "http"` and not `"transport": "http"`. ### 401 Unauthorized @@ -185,10 +201,12 @@ https://mcp.home.mendix.com/private \ ### Tools Not Showing Up +If your tools are not discovered after connection, verify the following: + * Wait 10–15 seconds after connecting for tool discovery to complete. * Run `claude mcp get mendix-cloud-mcp-private` to check the connection status. * If the status shows an error, remove and re-add the connection. ## Feedback -To report an issue or request additional API coverage, contact your Mendix CSM.Nidhi \ No newline at end of file +To report an issue or request additional API coverage, contact your Mendix CSM.