Mendix MCP Server

An MCP (Model Context Protocol) server that exposes the Mendix Model SDK, Mendix Platform API, Deploy API, and a running app's runtime OQL endpoint as a suite of tools an AI agent (e.g. Claude Code) can call.

In short: it lets an LLM read and modify a Mendix application model — create modules, entities, attributes, associations, pages, microflows, REST services, security rules, navigation, and enumerations — and then commit, deploy, or query the result, all through plain tool calls over HTTP.

Table of contents

• How it works

• Architecture

• The four Mendix surfaces it talks to

• The working-copy lifecycle (the core pattern)

• Request lifecycle

• Setup

• Configuration

• Running the server

• Connecting an MCP client

• Tool catalog

• Project layout

• How a typical task flows end-to-end

• Notes, limitations & gotchas

Related MCP server: CodeGraph

How it works

Mendix apps are not edited as loose files. The model lives on Mendix's Team Server, and the canonical way to change it programmatically is the Mendix Model SDK (mendixmodelsdk) driven through the Platform SDK (mendixplatformsdk). The pattern is always:

1. Open a temporary online working copy of an app from a branch.

2. Open its model (a live, typed, in-memory object graph of the whole app).

3. Read or mutate model elements (entities, pages, microflows, …).

4. Flush pending changes and commit the working copy back to the branch.

This server wraps that pattern in ~60 discrete MCP tools. Each tool is a thin, focused operation ("add an attribute to an entity", "add a widget to a page", "create a REST operation") that:

• takes an app_id (and usually a branch, defaulting to main),

• opens a fresh working copy + model,

• performs one well-scoped change,

• commits with a generated message,

• and returns a human/JSON result.

The AI agent orchestrates these small tools into larger changes. The server itself stays stateless — it holds no session between calls.

Architecture

┌───────────────────┐        JSON-RPC over HTTP (POST /mcp)        ┌────────────────────────┐
│   MCP client       │  ───────────────────────────────────────►  │   Mendix MCP Server     │
│ (Claude Code, etc.)│  ◄───────────────────────────────────────  │   (Node.js, port 3001)  │
└───────────────────┘         tool results / streamed events       └───────────┬────────────┘
                                                                                 │
                          ┌──────────────────────────────────────────────────────┼───────────────────────────┐
                          │                          │                            │                           │
                          ▼                          ▼                            ▼                           ▼
              ┌────────────────────┐   ┌──────────────────────────┐   ┌──────────────────────┐   ┌────────────────────┐
              │  Platform SDK       │   │   Deploy API (v2)         │   │  Runtime OQL endpoint │   │  Local FS / Web     │
              │  + Model SDK        │   │   deploy.mendix.com        │   │  /rest/oql/v1/query   │   │  (glob/read/write/  │
              │  (Team Server model)│   │                            │   │  on the running app   │   │   fetch/docs search)│
              └────────────────────┘   └──────────────────────────┘   └──────────────────────┘   └────────────────────┘
                       ▲                          ▲                            ▲
                   MENDIX_PAT              MENDIX_USERNAME +              MENDIX_RUNTIME_TOKEN
                                            MENDIX_API_KEY

Two source files form the spine:

• src/server.ts — the HTTP + MCP transport layer. Builds an McpServer, registers every tool group, and serves them over a Streamable HTTP transport at POST /mcp.

• src/mendix-client.ts — the shared Mendix helper layer: authentication, working-copy/model lifecycle, module/document lookup, multi-language text handling, and result formatting.

Everything else lives under src/tools/, one file per capability area, each exporting a registerXxxTools(server) function that server.ts calls.

The four Mendix surfaces it talks to

The server does not hit a single Mendix API. Different tools use different Mendix surfaces, each with its own credential:

The working-copy lifecycle (the core pattern)

Almost every model-mutating tool follows the same shape, implemented via helpers in src/mendix-client.ts:

// 1. Open a fresh working copy for the app/branch and open its model.
const wc = await getWorkingCopy(app_id, branch);   // createTemporaryWorkingCopy(branch)
const model = await wc.openModel();

// 2. Locate the target element.
const mod = findModule(model, moduleName);          // by name
const doc = findDocument(model, moduleName, docName); // recursive folder search

// 3. Mutate the in-memory model graph (create/update/delete SDK objects).
//    ...

// 4. Flush pending changes and commit the working copy back to the branch.
await commitWC(wc, model, "descriptive commit message", branch);

Read-only tools skip step 4 and just call getModel(app_id, branch) to open a throwaway working copy for inspection.

Key helpers in mendix-client.ts:

• mendix — the singleton MendixPlatformClient. Its PAT is bridged from MENDIX_PAT into the SDK's expected MENDIX_TOKEN mechanism via setPlatformConfig(...).

• getWorkingCopy(appId, branch) / getModel(appId, branch) — open a working copy / model.

• commitWC(wc, model, message, branch) — flushChanges() then commitToRepository(...).

• findModule / findDocument / splitQualifiedName — resolve Module.Element names, searching recursively through folders.

• setText / readText / getProjectLanguageCodes — Mendix user-visible text is never a plain string; it's a Text holding one Translation per configured language. setText writes a translation for every project language (avoiding consistency errors) and caches the language list per model.

• ok(msg) / json(data) / errorResult(err) — normalize tool return payloads.

• safe(handler) — wraps every tool handler so a thrown error becomes an MCP error result (isError: true) instead of crashing the server.

Request lifecycle

The HTTP layer in src/server.ts runs in stateless mode:

1. A client POSTs a JSON-RPC MCP message to http://localhost:3001/mcp.

2. The body is read and parsed.

3. A fresh McpServer + StreamableHTTPServerTransport pair is built per request. (An MCP server/transport pair can only be connect()-ed once — reusing it throws on the second call — so the server builds a new pair each time rather than holding a session.)

4. All tool groups are registered on that fresh server, it connects to the transport, and the transport handles the request/response.

5. On connection close, both transport and server are closed.

Any non-/mcp path returns 404. Errors are returned as JSON-RPC error objects (code: -32603).

Setup

Prerequisites

• Node.js (with support for ES modules / NodeNext; Node 18+ recommended for global fetch).

• A Mendix account with:

  • a Personal Access Token (PAT) with mx:modelrepository scopes (for model editing),

  • optionally an API key + username (for deployments),

  • optionally a runtime token (for live OQL queries).

• The Mendix app's App ID (found in the Mendix Portal / Developer Portal).

Install

npm install

Configuration

Copy .env.example to .env and fill in your credentials:

MENDIX_PAT=your_personal_access_token      # Model/Platform SDK — model editing
MENDIX_USERNAME=your@email.com             # Deploy API — deployments
MENDIX_API_KEY=your_deploy_api_key         # Deploy API — deployments
MENDIX_RUNTIME_TOKEN=your_runtime_token    # Runtime OQL — live data queries
PORT=3001                                  # HTTP port (default 3001)

.env is loaded automatically at startup via dotenv/config. Each credential is only required for the tools that use it — you can run model-editing tools with just MENDIX_PAT.

Running the server

# Type-check + compile TypeScript → dist/
npm run build

# Run the compiled server
npm start
# → Mendix MCP -> http://localhost:3001/mcp

# Or run directly from source during development (ts-node loader):
npm run dev

# Auto-restart on file changes:
npm run watch

Connecting an MCP client

Point any MCP client at the HTTP endpoint. For Claude Code, add an HTTP MCP server:

claude mcp add --transport http mendix http://localhost:3001/mcp

Or via a client config that supports Streamable HTTP transports, use the URL http://localhost:3001/mcp. Once connected, the client discovers all tools below and the agent can call them by name.

Tool catalog

All tools that touch the model accept app_id and (usually) an optional branch (default main). Grouped by source file:

Filesystem & knowledge — filesystem.ts, knowledge.ts

Platform / element document ops (ped_*) — ped.ts

Generic, low-level building blocks used by the higher-level tools.

Domain model — domain.ts

Supported attribute types: String, Integer, Long, Decimal, Boolean, DateTime, Enum, AutoNumber, Binary, HashString.

Enumerations, constants & snippets — enums.ts

Pages & widgets — pages.ts

Microflows / nanoflows — flows.ts

REST services — rest.ts

Security — security.ts

Navigation — navigation.ts

OQL — oql.ts

Deployment & project — deployment.ts

Project layout

mendix-mcp-server/
├── src/
│   ├── server.ts              # HTTP + MCP transport; registers all tool groups
│   ├── mendix-client.ts       # Auth, working-copy/model lifecycle, helpers
│   └── tools/
│       ├── filesystem.ts      # glob / read / write / fetch / read_skill
│       ├── knowledge.ts       # Mendix docs search
│       ├── ped.ts             # generic document/module ops (create/read/update/errors)
│       ├── domain.ts          # entities, attributes, associations
│       ├── enums.ts           # enumerations, constants, snippets
│       ├── pages.ts           # pages & widgets
│       ├── flows.ts           # microflows / nanoflows
│       ├── rest.ts            # consumed & published REST services, OpenAPI import
│       ├── security.ts        # user roles, page/microflow/entity access
│       ├── navigation.ts      # navigation menus
│       ├── oql.ts             # OQL generate + live read
│       └── deployment.ts      # commit, branch, deploy, export, settings
├── dist/                      # compiled output (npm run build)
├── package.json
├── tsconfig.json
├── .env / .env.example        # credentials & port
└── README.md

How a typical task flows end-to-end

Say the agent is asked: "Add a Customer entity to the Sales module with a Name field, put it on a data grid, and deploy to Sandbox."

1. entity_create → opens a working copy of the app, creates the Customer entity in Sales, commits.

2. entity_add_attribute → opens a fresh working copy, adds Name (String), commits.

3. ped_create_document → creates a CustomerOverview Page.

4. page_add_datagrid → wires a DataGrid to Sales.Customer with a column per attribute, commits.

5. navigation_add_menu_item → links the page into the navigation menu.

6. ped_check_errors → runs consistency checks to confirm the model is valid.

7. project_deploy → hits the Deploy API to push to the Sandbox environment.

8. project_get_deploy_status → polls until the deployment reports success.

Each step is a separate stateless HTTP call; the agent decides the order and reacts to each tool's result.

Notes, limitations & gotchas

• Stateless by design. No sessions are kept; each request builds and tears down its own MCP server/transport pair. This is intentional — the MCP SDK forbids reusing a connected pair.

• Every mutating call re-opens a working copy. Because tools are independent, a multi-step change is a series of commits, not one atomic transaction. Use project_commit to checkpoint and ped_check_errors to validate along the way.

• Text is multi-language. Any caption/label/title is a Text with one Translation per project language. Always use the setText/readText helpers (the higher-level tools do this for you) — don't assume a plain string.

• Entity persistence is expressed through the entity's generalization, not a standalone flag: a NoGeneralization with persistable=true/false, or a Generalization pointing at a parent entity (which then determines persistence).

• rest_import_openapi is pragmatic, not complete. It reads info.title, the server URL, and paths.*.<method>.operationId, but does not resolve $refs or import parameter/response schemas.

• Credential scoping. Model tools need only MENDIX_PAT; deploy tools additionally need MENDIX_USERNAME + MENDIX_API_KEY; oql_read needs MENDIX_RUNTIME_TOKEN. Missing credentials produce a clear error only when the relevant tool is called.

• Errors are non-fatal. The safe() wrapper converts thrown errors into MCP error results, so a failing tool call returns an error payload rather than taking the server down.