|
| 1 | +--- |
| 2 | +title: "Using Mendix Deploy APIs with AI Agents (MCP)" |
| 3 | +linktitle: "Deploy APIs with AI Agents (MCP)" |
| 4 | +url: /developerportal/deploy/deploy-apis-with-ai-agents/ |
| 5 | +weight: 86 |
| 6 | +description: "Describes how to connect AI coding assistants to Mendix Cloud using the Model Context Protocol (MCP), enabling AI agents to manage deployments, environments, and app lifecycle through natural language." |
| 7 | +--- |
| 8 | + |
| 9 | +## Introduction |
| 10 | + |
| 11 | +[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) enables AI coding assistants to connect to Mendix Cloud environments. Once connected, an AI assistant can manage deployments, environments, and the application lifecycle through natural language. |
| 12 | + |
| 13 | +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 Portal. |
| 14 | + |
| 15 | +{{% alert color="warning" %}} |
| 16 | +The use of AI tools is non-deterministic, outputs may vary between runs. AI Assistants/Agents will have permissions based on what the API Key and Personal Access Token (PAT) have access to. Through the [Backups API](/apidocs-mxsdk/apidocs/backups-api/) and [Logs](/developerportal/operate/logs/), they may have access to production environments and Personally Identifiable Information (PII) contained within your environments. Carefully review and limit the scope of credentials before use. |
| 17 | +{{% /alert %}} |
| 18 | + |
| 19 | +## Prerequisites |
| 20 | + |
| 21 | +Before you start, make sure you have the following: |
| 22 | + |
| 23 | +* An MCP-compatible AI client that supports custom request headers, such as Claude Code or VS Code with GitHub Copilot |
| 24 | +* A Mendix account with API access enabled |
| 25 | +* A [Personal Access Token (PAT)](/portal/user-settings/#pat) with the `mx:deployment:write` and `mx:deployment:read` scopes selected |
| 26 | +* A [Mendix API key](/portal/user-settings/#profile-api-keys) |
| 27 | + |
| 28 | +## Connecting Your AI Assistant {#connecting} |
| 29 | + |
| 30 | +### Claude Code {#claude-code} |
| 31 | + |
| 32 | +To add the Mendix MCP server in Claude Code, run the following command in your terminal: |
| 33 | + |
| 34 | +```bash |
| 35 | +claude mcp add --scope user --transport http mendix-cloud-mcp \ |
| 36 | +https://mcp.home.mendix.com/ \ |
| 37 | +--header "Authorization: MxToken {GENERATED_PAT}" \ |
| 38 | +--header "Mendix-Username: {Mendix-Username}" \ |
| 39 | +--header "Mendix-ApiKey: {Mendix-ApiKey}" |
| 40 | +``` |
| 41 | + |
| 42 | +Replace the following placeholders with your credentials: |
| 43 | + |
| 44 | +* `{GENERATED_PAT}` – the generated Mendix Personal Access Token (PAT) |
| 45 | +* `{Mendix-Username}` – the login name of the user making the request, with the required privileges in the Mendix Platform |
| 46 | +* `{Mendix-ApiKey}` – the API key associated with that user |
| 47 | + |
| 48 | + |
| 49 | +To verify the connection, run the following command: |
| 50 | + |
| 51 | +```bash |
| 52 | +claude mcp get mendix-cloud-mcp |
| 53 | +``` |
| 54 | + |
| 55 | +A successful connection displays output similar to the following: |
| 56 | + |
| 57 | +```bash |
| 58 | +claude mcp get mendix-cloud-mcp |
| 59 | +mendix-cloud-mcp: |
| 60 | + Scope: User config (available in all your projects) |
| 61 | + Status: ✔ Connected |
| 62 | + Type: http |
| 63 | + URL: https://mcp.home.mendix.com/ |
| 64 | + Headers: |
| 65 | + Authorization: MxToken {GENERATED_PAT} |
| 66 | + Mendix-Username: {Mendix-Username} |
| 67 | + Mendix-ApiKey: {Mendix-ApiKey} |
| 68 | + |
| 69 | +To remove this server, run: claude mcp remove mendix-cloud-mcp -s user |
| 70 | +``` |
| 71 | + |
| 72 | +### VS Code with GitHub Copilot {#vs-code} |
| 73 | + |
| 74 | +To add the Mendix MCP server in VS Code, add the following configuration to your `.vscode/settings.json` file or your VS Code user settings: |
| 75 | + |
| 76 | +```json |
| 77 | +{ |
| 78 | + "mcp":{ |
| 79 | + "servers":{ |
| 80 | + "mendix-cloud-mcp":{ |
| 81 | + "type":"http", |
| 82 | + "url":"https://mcp.home.mendix.com/", |
| 83 | + "headers":{ |
| 84 | + "Authorization":"MxToken {GENERATED_PAT}", |
| 85 | + "Mendix-Username":"{Mendix-Username}", |
| 86 | + "Mendix-ApiKey":"{Mendix-ApiKey}" |
| 87 | + } |
| 88 | + } |
| 89 | + } |
| 90 | + } |
| 91 | +} |
| 92 | +``` |
| 93 | + |
| 94 | +Replace the placeholder values with your credentials as described in the [Claude Code](#claude-code) section above. |
| 95 | + |
| 96 | +## Available Capabilities {#capabilities} |
| 97 | + |
| 98 | +Once connected, your AI assistant has access to the following capabilities. |
| 99 | + |
| 100 | +### Apps and Environments |
| 101 | + |
| 102 | +| Action | Example Prompt | |
| 103 | +| --- | --- | |
| 104 | +| List your apps | "Show me all my Mendix apps" | |
| 105 | +| View environments | "What environments does my app have?" | |
| 106 | +| Get environment details | "Show me the details of the production environment" | |
| 107 | +| Start or stop an environment | "Stop the acceptance environment of my-app" | |
| 108 | +| Scale an environment | "Scale production to 2 instances" | |
| 109 | +| View environment settings | "Show the constants for production" | |
| 110 | +| Update environment settings | "Set the constant `DB_TIMEOUT` to 30 in acceptance" | |
| 111 | +| Tag an environment | "Add a tag 'release-2.3' to the acceptance environment" | |
| 112 | +| Clean an environment | "Clean the test environment" | |
| 113 | +| Create a Free App | "Create a free app for project X" | |
| 114 | + |
| 115 | +### Deployments and Packages |
| 116 | + |
| 117 | +| Action | Example Prompt | |
| 118 | +| --- | --- | |
| 119 | +| List packages | "Show all deployment packages for my-app" | |
| 120 | +| Build a package | "Build version 2.3.5 from the main branch" | |
| 121 | +| Deploy a package | "Transport the latest package to production" | |
| 122 | +| Delete a package | "Delete the oldest unused package" | |
| 123 | +| Check deployment status | "What's the status of the current deployment?" | |
| 124 | + |
| 125 | +### Backups |
| 126 | + |
| 127 | +| Action | Example Prompt | |
| 128 | +| --- | --- | |
| 129 | +| List snapshots | "Show me all backups for the production environment" | |
| 130 | +| Create a snapshot | "Create a backup of production before deploying" | |
| 131 | +| Download a backup | "Download the latest database backup" | |
| 132 | +| Restore from a snapshot | "Restore acceptance from the last production snapshot" | |
| 133 | + |
| 134 | +### Logs |
| 135 | + |
| 136 | +| Action | Example Prompt | |
| 137 | +| --- | --- | |
| 138 | +| Get access logs | "Download access logs for production from yesterday" | |
| 139 | +| Get application logs | "Get the runtime logs for acceptance on 2025-01-15" | |
| 140 | + |
| 141 | +### Permissions |
| 142 | + |
| 143 | +| Action | Example Prompt | |
| 144 | +| --- | --- | |
| 145 | +| View permissions | "Who has access to the production environment?" | |
| 146 | +| Update permissions | "Give `user@company.com` deploy access to acceptance" | |
| 147 | +| Update Technical Contact | "Set `jane@company.com` as the Technical Contact" | |
| 148 | + |
| 149 | +## Authentication {#authentication} |
| 150 | + |
| 151 | +Your credentials are passed directly to the Mendix APIs and are not stored or inspected by the MCP gateway. Each user authenticates using their own credentials. |
| 152 | + |
| 153 | +Two authentication methods are used depending on the API: |
| 154 | + |
| 155 | +| API Version | Headers Required | |
| 156 | +| --- | --- | |
| 157 | +| Deploy API v4, App Permissions | `Authorization: MxToken {GENERATED_PAT}` | |
| 158 | +| Deploy API v1/v2, Build API, Backups API | `Mendix-Username` and `Mendix-ApiKey` | |
| 159 | + |
| 160 | +{{% alert color="info" %}} |
| 161 | +Include all three headers in your connection configuration to ensure all tools work correctly. |
| 162 | +{{% /alert %}} |
| 163 | + |
| 164 | + |
| 165 | +## Client Compatibility {#compatibility} |
| 166 | + |
| 167 | +The Mendix MCP integration works with any MCP-compatible client that supports HTTP transport (streamable HTTP) and custom headers for authentication. |
| 168 | + |
| 169 | +{{% alert color="warning" %}} |
| 170 | +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 token and API key-based authentication. |
| 171 | +{{% /alert %}} |
| 172 | + |
| 173 | +## Known Limitations {#limitations} |
| 174 | + |
| 175 | +The following limitations apply: |
| 176 | + |
| 177 | +| Limitation | Details | |
| 178 | +| --- | --- | |
| 179 | +| 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. | |
| 180 | +| Rate limiting | Requests are limited to 60 per minute. High-volume automated workflows may exceed this limit. | |
| 181 | +| OAuth-only clients | Clients that exclusively use OAuth 2.0 for MCP authentication cannot connect. | |
| 182 | + |
| 183 | +## Troubleshooting {#troubleshooting} |
| 184 | + |
| 185 | +### Connection Fails or Times Out |
| 186 | + |
| 187 | +* Make sure the URL is exactly `https://mcp.home.mendix.com/`. The trailing slash (`/`) is required. |
| 188 | +* Verify that your JSON configuration uses `"type": "http"` and not `"transport": "http"`. |
| 189 | + |
| 190 | +### 401 Unauthorized |
| 191 | + |
| 192 | +Your credentials are incorrect or have expired. Regenerate your PAT and verify that your API key is still active. |
| 193 | + |
| 194 | +### 403 Forbidden |
| 195 | + |
| 196 | +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/). |
| 197 | + |
| 198 | +### 406 Not Acceptable |
| 199 | + |
| 200 | +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: |
| 201 | + |
| 202 | +```bash |
| 203 | +claude mcp remove mendix-cloud-mcp |
| 204 | +claude mcp add --scope user --transport http mendix-cloud-mcp \ |
| 205 | +https://mcp.home.mendix.com/ \ |
| 206 | +--header "Authorization: MxToken {GENERATED_PAT}" \ |
| 207 | +--header "Mendix-Username: {Mendix-Username}" \ |
| 208 | +--header "Mendix-ApiKey: {Mendix-ApiKey}" |
| 209 | +``` |
| 210 | + |
| 211 | +### Tools Not Showing Up |
| 212 | + |
| 213 | +* Wait 10–15 seconds after connecting for tool discovery to complete. |
| 214 | +* Run `claude mcp get mendix-cloud-mcp` to check the connection status. |
| 215 | +* If the status shows an error, remove and re-add the connection. |
| 216 | + |
| 217 | +## Feedback |
| 218 | + |
| 219 | +To report an issue or request additional API coverage, contact your Mendix CSM. |
0 commit comments