Skip to content

Commit d3f28fd

Browse files
Nidhi251289Nidhi251289
committed
New MCP doc for Private cloud APIs
1 parent bd9220b commit d3f28fd

1 file changed

Lines changed: 194 additions & 0 deletions

File tree

‎content/en/docs/deployment/private-cloud/private-cloud-api-mcp.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
---
2+
title: "Using Mendix on K8s Deploy and Build APIs with AI Agents (MCP)"
3+
url: /developerportal/deploy/deploy-mxonk8s-apis-with-ai-agents/
4+
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."
5+
weight: 100
6+
---
7+
8+
## Introduction
9+
10+
[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.
11+
12+
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.
13+
14+
{{% alert color="warning" %}}
15+
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.
16+
{{% /alert %}}
17+
18+
## Prerequisites
19+
20+
Before you start, make sure you have the following:
21+
22+
* An MCP-compatible AI client that supports custom request headers, such as Claude Code or VS Code with GitHub Copilot
23+
* A Mendix account with API access enabled
24+
* 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/)
25+
* 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/)
26+
27+
## Connecting Your AI Assistant {#connecting}
28+
29+
### Claude Code {#claude-code}
30+
31+
To add the Mendix MCP server in Claude Code, run the following command in your terminal:
32+
33+
```bash
34+
claude mcp add --scope user --transport http mendix-cloud-mcp-private \
35+
https://mcp.home.mendix.com/private \
36+
--header "Authorization: MxToken {GENERATED_PAT}"
37+
```
38+
39+
Replace the following placeholders with your credentials:
40+
41+
* `{GENERATED_PAT}` – the generated Mendix Personal Access Token (PAT)
42+
43+
44+
To verify the connection, run the following command:
45+
46+
```bash
47+
claude mcp get mendix-cloud-mcp-private
48+
```
49+
50+
A successful connection displays output similar to the following:
51+
52+
```bash
53+
claude mcp get mendix-cloud-mcp-private
54+
mendix-cloud-mcp-private:
55+
Scope: User config (available in all your projects)
56+
Status: ✔ Connected
57+
Type: http
58+
URL: https://mcp.home.mendix.com/private
59+
Headers:
60+
Authorization: MxToken {GENERATED_PAT}
61+
62+
To remove this server, run: claude mcp remove mendix-cloud-mcp -s user
63+
```
64+
65+
### VS Code with GitHub Copilot {#vs-code}
66+
67+
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:
68+
69+
```json
70+
{
71+
"mcp":{
72+
"servers":{
73+
"mendix-cloud-mcp-private":{
74+
"type":"http",
75+
"url":"https://mcp.home.mendix.com/private",
76+
"headers":{
77+
"Authorization":"MxToken {GENERATED_PAT}"
78+
}
79+
}
80+
}
81+
}
82+
}
83+
```
84+
85+
Replace the placeholder values with your credentials as described in the [Claude Code](#claude-code) section above.
86+
87+
## Available Capabilities {#capabilities}
88+
89+
Once connected, your AI assistant has access to the following capabilities.
90+
91+
### Apps and Environments
92+
93+
| Action | Example Prompt |
94+
| --- | --- |
95+
| Get namespace manifest | `mx:deployment:read` or `mx:deployment:write` |
96+
| Get namespaces manifest | `mx:deployment:read` or `mx:deployment:write` |
97+
| Get cluster manifest | `mx:deployment:read` or `mx:deployment:write` |
98+
| Get clusters manifest | `mx:deployment:read` or `mx:deployment:write` |
99+
| Create cluster | `mx:deployment:write` |
100+
| Update cluster | `mx:deployment:write` |
101+
| Delete cluster | `mx:deployment:write` |
102+
| Create namespace | `mx:deployment:write` |
103+
| Update namespace | `mx:deployment:write` |
104+
| Delete namespace | `mx:deployment:write` |
105+
| Get environment manifest | `mx:deployment:read` or `mx:deployment:write` |
106+
| Get multiple environment manifest| `mx:deployment:read` or `mx:deployment:write` |
107+
| Create environment | `mx:deployment:write` |
108+
| Update environment | `mx:deployment:write` |
109+
| Delete environment | `mx:deployment:write` |
110+
| Get apps manifest | `mx:deployment:write` and `mx:app:metadata:read` |
111+
| Get app manifest | `mx:deployment:write` and `mx:app:metadata:read` |
112+
| Get job | `mx:deployment:read` and `mx:deployment:write` |
113+
114+
115+
### Deployments and Packages
116+
117+
| Action | Example Prompt |
118+
| --- | --- |
119+
| Build deployment package | `mx:privatecloud-build:write` and `mx:modelrepository:write` |
120+
| Upload deployment package | `mx:privatecloud-build:write` |
121+
| Delete deployment package | `mx:privatecloud-build:write` |
122+
| Get deployment package | `mx:privatecloud-build:read` or `mx:privatecloud-build:write` |
123+
| Get deployment package list | `mx:privatecloud-build:read` or `mx:privatecloud-build:write` |
124+
| Get Job | `mx:privatecloud-build:read` or `mx:privatecloud-build:write` |
125+
126+
## Authentication {#authentication}
127+
128+
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.
129+
130+
Two authentication methods are used depending on the API:
131+
132+
| API Version | Headers Required |
133+
| --- | --- |
134+
| Deploy API v4, App Permissions | `Authorization: MxToken {GENERATED_PAT}` |
135+
136+
{{% alert color="info" %}}
137+
Include all three headers in your connection configuration to ensure all tools work correctly.
138+
{{% /alert %}}
139+
140+
141+
## Client Compatibility {#compatibility}
142+
143+
The Mendix on Kubernetes MCP integration works with any MCP-compatible client that supports HTTP transport (streamable HTTP) and custom headers for authentication.
144+
145+
{{% alert color="warning" %}}
146+
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.
147+
{{% /alert %}}
148+
149+
## Known Limitations {#limitations}
150+
151+
The following limitations apply:
152+
153+
| Limitation | Details |
154+
| --- | --- |
155+
| 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. |
156+
| Rate limiting | Requests are limited to 60 per minute. High-volume automated workflows may exceed this limit. |
157+
| OAuth-only clients | Clients that exclusively use OAuth 2.0 for MCP authentication cannot connect. |
158+
159+
## Troubleshooting {#troubleshooting}
160+
161+
### Connection Fails or Times Out
162+
163+
* Make sure the URL is exactly `https://mcp.home.mendix.com/private`
164+
* Verify that your JSON configuration uses `"type": "http"` and not `"transport": "http"`.
165+
166+
### 401 Unauthorized
167+
168+
Your credentials are incorrect or have expired. Regenerate your PAT and verify that your API key is still active.
169+
170+
### 403 Forbidden
171+
172+
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/).
173+
174+
### 406 Not Acceptable
175+
176+
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:
177+
178+
```bash
179+
claude mcp remove mendix-cloud-mcp-private
180+
claude mcp add --scope user --transport http mendix-cloud-mcp \
181+
https://mcp.home.mendix.com/private \
182+
--header "Authorization: MxToken {GENERATED_PAT}" \
183+
--header "Mendix-Username: {Mendix-Username}" \
184+
```
185+
186+
### Tools Not Showing Up
187+
188+
* Wait 10–15 seconds after connecting for tool discovery to complete.
189+
* Run `claude mcp get mendix-cloud-mcp-private` to check the connection status.
190+
* If the status shows an error, remove and re-add the connection.
191+
192+
## Feedback
193+
194+
To report an issue or request additional API coverage, contact your Mendix CSM.Nidhi

0 commit comments

Comments
 (0)