Using Mendix on K8s Deploy and Build APIs with AI Agents (MCP)

Introduction

Model Context Protocol (MCP) 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.

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) with the mx:deployment:write and mx:deployment:read scopes selected for Deploy APIs
• A Personal Access Token (PAT) with the mx:privatecloud-build:read, mx:privatecloud-build:write and mx:modelrepository:write scopes selected for Build APIs

Connecting Your AI Assistant

Refer to the following sections for information about connecting your agent.

Claude Code

To add the Mendix MCP server in Claude Code, perform the following steps:

1. Run the following command in your terminal:

   claude mcp add --scope user --transport http mendix-cloud-mcp-private \
   https://mcp.home.mendix.com/private \
   --header "Authorization: MxToken {GENERATED_PAT}"

2. Replace the following placeholders with your credentials:

   • {GENERATED_PAT} - Replace with the generated Mendix Personal Access Token (PAT)

3. Verify the connection by running the following command:

   claude mcp get mendix-cloud-mcp-private

   A successful connection displays output similar to the following:

   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:

claude mcp remove mendix-cloud-mcp -s user

VS Code with GitHub Copilot

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:

{
   "mcp":{
      "servers":{
         "mendix-cloud-mcp-private":{
            "type":"http",
            "url":"https://mcp.home.mendix.com/private",
            "headers":{
               "Authorization":"MxToken {GENERATED_PAT}"
            }
         }
      }
   }
}

2. Replace the placeholder values with your credentials as described in the Claude Code section above.

Available Capabilities

Once connected, your AI assistant has access to the following capabilities.

Apps and Environments

Deployments and Packages

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:

Client Compatibility

The Mendix on Kubernetes MCP integration works with any MCP-compatible client that supports HTTP transport (streamable HTTP) and custom headers for authentication.

Known Limitations

The following limitations apply:

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

Connection Fails or Times Out

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

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.

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:

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

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.