Version: 3.2

MTA Exploratory Free Edition Setup Guide

Welcome to the Menditect Test Automation (MTA) Exploratory Free Edition.

This guide provides step-by-step instructions to configure and run AI-assisted exploratory testing on your local Mendix application without requiring a paid MTA Cloud license.

MTA Exploratory provides in-memory test execution directly inside your running Mendix Java Virtual Machine (JVM). When your AI assistant executes an exploratory test:

It creates test objects and parameters in-memory.
It executes your target microflows with isolated test payloads.
It automatically rolls back database transactions (RollbackTcseAfterExecution: Yes), keeping your application data clean.
It analyzes runtime telemetry (variable values, return data, execution times, and rule evaluations) and presents immediate results.

Choose Your Setup Path

The MTA Runtime Plugin is required for all setups. You can choose how your AI assistant interacts with your Mendix application:

                                  ┌──────────────────────────────────────────────┐
                                  │      COMMON PREREQUISITE: MTA PLUGIN         │
                                  │   Install & configure in Mendix Studio Pro   │
                                  └──────────────────────┬───────────────────────┘
                                                         │
                        ┌────────────────────────────────┴────────────────────────────────┐
                        │                                                                 │
                        ▼                                                                 ▼
      ┌───────────────────────────────────┐                             ┌───────────────────────────────────┐
      │             VARIANT 1             │                             │             VARIANT 2             │
      │            Mendix MAIA            │                             │      Agentic Test Workspace       │
      │      (Studio Pro Built-in         │                             │  (External AI IDEs: Cursor,       │
      │       Mendix AI Assistant)        │                             │   VS Code, Antigravity, Claude)   │
      └───────────────────────────────────┘                             └───────────────────────────────────┘

Feature / Aspect	Variant 1: Mendix MAIA	Variant 2: Agentic Test Workspace
Primary Environment	Inside Mendix Studio Pro (11.12+)	External AI IDE (Cursor, VS Code, Antigravity, Claude Code)
Model Inspection	Live native Studio Pro model context	Headless and offline via `mxcli` + local SQLite `catalog.db`
Testing Skills Location	Marketplace module: `Menditect_AgenticTestSkills`	Project or workspace `./skills/` directory
Git Impact on Mendix	Skills module committed to Mendix repository	Zero impact (isolated in dedicated tools workspace)
Best For	Developers working entirely within Mendix Studio Pro	Developers using modern AI coding IDEs and multi-agent setups

Common Step: Install and Configure the MTA Plugin in Studio Pro

The MTA Plugin embeds a lightweight, secure Model Context Protocol (MCP) server directly inside your running Mendix application. This step is identical for both variants.

1. Download and Import the MTA Plugin Module

In Mendix Studio Pro, open the Marketplace (or visit the public Menditect Test Automation Plugin component (Marketplace Component 214717)).
Download and import the MTA Plugin module into your Mendix project.

Ensure you are using a version that includes the embedded MCP server:
- Mendix 9: Version 9.5.3 or higher
- Mendix 10: Version 10.5.3 or higher
- Mendix 11: Version 11.5.3 or higher
If prompted, ensure standard module dependencies (such as CommunityCommons) are updated.

2. Configure MTA Plugin Constants

In Mendix Studio Pro App Explorer, open App > Marketplace modules > MtaPluginModule > Constants (or configure them under Settings > Configurations > Edit > Constants):

Constant Name	Value	Description and Rationale
`MtaPluginModule.ApplicationInstanceToken`	`{YOUR_UNIQUE_TOKEN}`	Paste the personal token provided in your Menditect welcome email.
`MtaPluginModule.ConnectionMethod`	`AfterStartup`	Connects the plugin automatically whenever the application starts.
`MtaPluginModule.EnableMcpServer`	`True`	Activates the local `/plugin/mcp` endpoint for your AI assistant.
`MtaPluginModule.MTAConnectionUrl`	`wss://services.menditect.com`	The Menditect connection WebSocket gateway URL.
`MtaPluginModule.MTAConnectionUsername`	`MTAConnectionUser`	Default username for the plugin connection.
`MtaPluginModule.MTAConnectionPassword`	`c0Nn3cT-mTa-PlUg1n!`	Default password for the connection gateway.
`MtaPluginModule.McpServerAccessToken`	(Choose your own secret key)	e.g. `MySecretToken123`. This secret token protects your local MCP endpoint from unauthorized access.

[!IMPORTANT] Make note of the secret value you enter for MtaPluginModule.McpServerAccessToken. You will provide this token to your AI assistant / workspace configuration.

3. Verify Startup Microflow

If your project already defines an After Startup microflow under App > Settings > Runtime:

Open your existing After Startup microflow.
Add a microflow call activity to execute MtaPluginModule.ASU_Setup_Connection_MTA.

4. Start Your Application Locally

Press F5 (or click Run Locally) in Studio Pro.
Ensure the application starts cleanly. The MTA plugin is now actively listening for MCP requests on http://localhost:8081/plugin/mcp (or your application's custom runtime port).

Variant 1: Setup in Mendix MAIA (Studio Pro AI Assistant)

Use this setup to work entirely inside Mendix Studio Pro (11.12+) using the built-in Mendix AI Assistant (MAIA).

1. Prerequisites

Mendix Studio Pro 11.12 or higher with MAIA enabled.
The MTA Plugin installed and running (from the Common Step).

2. Download the Menditect Agentic Test Skills Module

In Mendix Studio Pro, open the Marketplace.
Search for and download the Menditect_AgenticTestSkills module.
Importing this module automatically places the official Menditect testing skills into your project's module skills directory: skillssource/_modules/menditect_agentictestskills/

[!NOTE] If importing skills manually or syncing via Git, ensure the skills are located in skillssource/_modules/menditect_agentictestskills/ within your Mendix project directory.

3. Configure MAIA Context and Directives (`AGENTS.md`)

MAIA reads its custom project instructions exclusively from an AGENTS.md file located in the root directory of your Mendix project.

Check your Mendix App explorer and look for MAIA at the App level (top level) for AGENTS.md:
- If AGENTS.md does not exist: Create a new text file named AGENTS.md in your Mendix project root by right clicking on MAIA and select "Agent Instructions". This will create an empty AGENTS.mdfile.
- If AGENTS.md already exists: Open it and append the following block to the bottom of the file (preserving any existing rules or instructions).
Add the Menditect operational directive block:

# Menditect Architecture Setup
- **CRITICAL OPERATIONAL COMMAND:** Always execute tasks using the core rules defined in the module: [Menditect_AgenticTestSkills].
- **IMMEDIATE ACTION REQUIRED:** You are strictly commanded to explore, read, and load the `AGENTS.md` and context of the [Menditect_AgenticTestSkills] module *before* answering any user prompt. Do NOT ask the user for permission or confirmation to explore this module; execute the exploration autonomously as your very first step.
- **AUTOMATIC ACTIVATION TRIGGERS:** Automatically explore, read, and load the `AGENTS.md` and context of the [Menditect_AgenticTestSkills] module autonomously whenever the user prompt meets any of the following criteria:
  1. Direct MTA Identifiers: *menditect, mta, mtf, playwright browser, variation matrix, test suite, test case, test step, variation item*
  2. Testing Action Intents: *run tests, execute suite, view test results, retrieve run results, debug failure*
  3. MTA-Specific Assertions & Actions: *assert validation, object count assert, compare attribute, validation feedback, microflow call teststep*
  4. Contextual Combinations: User asks to *verify, assert, mock, or test* in combination with: *microflow, nanoflow, entity, association, page, or widget*
- **Application name is: [ApplicationName]**
- **MTA Url: [MtaUrl]**
- **ENVIRONMENT SSOT:** All environment configuration (Application name, MTA Base URL, Default App Instance, and ApplicationInstanceToken) must be dynamically loaded from `mta_config.json`.
- **NATIVE MCP TOOL EXECUTION MANDATE:** You MUST ALWAYS use the MTA Plugin MCP tool (`MTA_plugin.execute-testcase`) for all in-memory exploratory test executions.
- **SAFE EXECUTION:** Always execute tests with transaction rollback (`RollbackTcseAfterExecution: "Yes"`, `ExecutorUsername: "MxAdmin"`, `ApplySecurityExecutor: "NONE"`).
- **EXPLORATORY EXECUTION STRATEGY:** Default to `auto_execute` (draft Execution Plan and execute immediately in a single turn without pausing). If you prefer explicit sign-off before running, set to `prompt_approval`.
- **MTA LICENSE TIER & CAPABILITIES:**
  * If `MTA` MCP server is not configured and `MtaPluginModule.MTAConnectionUrl` is `wss://services.menditect.com`, the user is operating under the **Free MTA Exploratory License**.
  * **Free Capabilities:** Unlimited local in-memory microflow testing (`execute-testcase`) and local Execution Plan generation (`EP_*.md`).
  * **Paid Platform Capabilities:** Persistent cloud/on-prem test suites, Playwright Frontend UI testing, and CI/CD automated regression pipelines require a paid MTA Platform License.
- **MCP SUBPROCESS PROTECTION & TOKEN ROTATION:** NEVER execute terminal commands (`Stop-Process`, `taskkill`, `kill`) against running MCP server/proxy processes (`mta-proxy.js`, `node.exe`, or custom proxies). Terminating stdio child processes causes AI IDEs (Antigravity, Cursor, Claude Desktop, VS Code) to permanently disable MCP servers for the active session. The built-in proxy reloads `.env` dynamically on every request with zero restart needed. If using a static or custom proxy that returns HTTP 401, prompt the user to update their credentials and use their IDE's "Restart MCP Server" / "Reload Window" UI action.

Configure your ExecutorUsername: By default, test execution runs under the MxAdmin user context. If MxAdmin is not present in your Mendix app's user database, you can specify a different existing administrator or test username (e.g. ExecutorUsername: "Admin" or ExecutorUsername: "TestUser") in your AGENTS.md directives, see step 2 above.
Set the EXPLORATORY EXECUTION STRATEGY: Default to auto_execute (draft Execution Plan and execute immediately in a single turn without pausing). If you prefer explicit sign-off before running, set to prompt_approval.

4. Connect MAIA to the Local MTA Plugin MCP Server

Configure MAIA's MCP tool settings in Studio Pro (or within your environment MCP configuration), see https://docs.mendix.com/refguide/maia-mcp/#adding-server:

Server Name: MTA_plugin
URL: http://localhost:[YourPort]/plugin/mcp)
Connection type: HTTP
Authentication: Bearer Token: use the exact value set in MtaPluginModule.McpServerAccessToken

[!TIP] Don't forget to enable the execute-testcase tool in the MCP Settings pane.

5. Execute an Exploratory Test in MAIA

Ensure your Mendix app is running (F5).
Open the MAIA Chat panel inside Mendix Studio Pro.
Prompt MAIA:

Using the Menditect Agentic Test Skills module, execute an exploratory test for microflow MyModule.SUB_CalculateDiscount on my running app. Verify boundary conditions and check return values.

MAIA Execution Process:
- MAIA reads the microflow directly from your active Studio Pro model.
- It composes the in-memory test payload (TCEX_RQ) following the patterns in Menditect_AgenticTestSkills.
- It sends the request to the local MTA Plugin MCP server (execute-testcase).
- The microflow executes in the JVM and rolls back immediately.
- MAIA displays the execution telemetry, step durations, and verified return values in the chat.

Variant 2: Setup via Agentic Test Workspace (External AI IDE)

Use this setup to write and run tests using external AI IDEs such as Cursor, VS Code (GitHub Copilot / Cline), Google Antigravity / Gemini, or Claude Code.

The agentic-test-workspace is a pre-configured tools workspace that orchestrates Menditect testing skills, offline model inspection, and local MCP tool bridging for AI coding assistants.

Why Use the Agentic Test Workspace?

Multi-IDE Automation: Automatically configures MCP tool definitions, security permissions, and agent directives for Cursor (.cursor/mcp.json), VS Code (.vscode/mcp.json), Claude Code (.claude/settings.json), and Google Antigravity (mcp_config.json) with zero manual JSON editing.
Offline Model Search & AST Analysis (mxcli): Includes a built-in Mendix model indexer (mxcli) that converts your .mpr project file into an optimized local SQLite catalog (.mxcli/catalog.db). This allows AI assistants to perform sub-second microflow lookups, trace callers/callees, and inspect domain models completely offline.
Zero Git Clutter: The dedicated tools workspace operates in an isolated directory alongside your Mendix project, keeping your core Mendix Git repository completely clean of test scripts, logs, and local tokens.
Dynamic MCP Token Bridging: Embeds a local proxy (mta-proxy.js) that connects stdio-based AI IDEs to the running Mendix runtime's HTTP MCP endpoint, dynamically reloading tokens from .env without requiring IDE restarts.

For in-depth architecture details and command references, see the agentic-test-workspace README.

1. Prerequisites

Node.js (v18+) installed.
Git installed.

2. Create and open your workspace directory

Create a dedicated folder for your workspace on your local disk and navigate into it:

# Create your workspace directory (replace 'C:\projects\your-workspace' with your preferred path)
mkdir C:\projects\your-workspace

# Navigate into the newly created workspace directory
cd C:\projects\your-workspace

3. Clone the repository

Clone the agentic-test-workspace repository inside your workspace directory:

git clone https://github.com/Menditect/agentic-test-workspace.git

4. Go to agentic-test-workspace directory

Navigate into the cloned repository folder:

cd agentic-test-workspace

5. Run the Setup Wizard

Run the interactive setup script:

npm run setup

Follow the prompts step-by-step:

Accept Disclaimer: Press Enter to accept y.
Workspace Option: Choose [1] Dedicated Tools Workspace (Recommended) to keep your Mendix project repository clean.
Local Mendix App Path: Enter the path to your Mendix project (e.g. C:\Users\YourName\Mendix\MyApp). The wizard will detect your .mpr file and Mendix version automatically.
Model Inspection Source: Select [1] mxcli (recommended). This allows the AI to inspect microflows and domain models offline.
Project Search Index: Select [1] Fast (recommended) to compile the SQLite catalog (.mxcli/catalog.db) in seconds.
MTA Application Instances (Cloud Execution): When asked "Do you have an MTA Application Instance to configure? (y/n)", enter n. (Exploratory testing runs locally and does not require cloud instances).
Application Name: Press Enter to accept the detected project name.
MTA URL: Default is https://services.menditect.com. (Note: For free exploratory users, the cloud MTA URL is not relevant because all testing runs locally on your machine. You can safely press Enter to accept the default or leave it empty).
Identification token for a service account: Press Enter to SKIP (leave blank). (You do not need an MTA Cloud license or service account token for exploratory testing).
App Under Test Plugin URL: Press Enter to accept http://localhost:[YourPort]/plugin/mcp (or enter your custom port if different).
App Under Test Plugin Token: Enter Bearer followed by the secret token you chose in Studio Pro for MtaPluginModule.McpServerAccessToken (e.g. Bearer MySecretToken123).
Exploratory Execution Strategy (exploratory_execution_mode):
- Choose [1] auto_execute (recommended): High-velocity 1-turn testing. The AI writes the complete Execution Plan (EP_*.md) to disk and dispatches the test immediately in the very same turn (< 3 seconds total feedback). Transactions are safely rolled back in memory, and the test plan remains on disk ready for permanent promotion to MTA at any time.
- Choose [2] prompt_approval: Traditional governed flow. The AI drafts the Execution Plan and pauses at Checkpoint 1, waiting for your explicit approval before executing.
Review & Confirm Configuration: The wizard displays your complete configuration summary (including setting mta_license_tier to free_exploratory / auto). Type 9 if you wish to toggle the exploratory mode, or press Enter (y) to confirm and write mta_config.json and .env.
Verify the Setup: The wizard automatically verifies the setup and configuration of the MTA Plugin MCP server as the final step.

[TIP!] Make sure the app is running in StudioPro

You can also Verify the Setup Manually at any time.

Execute from the agentic-test-workspace directory in your workspace:

npm run verify

The verify tool will confirm:

mta_config.json and .env are properly structured.
mxcli offline model inspection is active.
Local MTA_plugin MCP endpoint is reachable and authenticated.

6. Open Your AI IDE and Execute Your First Test

Open the parent workspace directory (e.g. C:\projects\mta-workspace) in Cursor, VS Code, or Antigravity (or run claude in that directory).
All MCP configurations (.cursor/mcp.json, .vscode/mcp.json, .claude/settings.json) and agent directives (AGENTS.md) are automatically loaded.
You can instruct your AI assistant to configure its own MCP server settings dynamically by using this prompt:

Read `mta_config.json` and `.env` in this workspace, and configure your MCP client settings to connect to the`mta_plugin` server (`plugin_mcp_url`) using the corresponding Bearer token.

Once the MTA Plugin MCP server is properly configured, prompt your assistant in the chat:

Please inspect the microflow MyModule.SUB_CalculateDiscount using mxcli, 
and execute an exploratory unit test with all boundary values on my running app using the MTA_plugin tool.

How Exploratory Test Execution Works

Regardless of whether you use Variant 1 (MAIA) or Variant 2 (Agentic Workspace), the underlying exploratory execution engine operates under the same protocol:

Execution Strategy & Plan Governance (`exploratory_execution_mode`)

Even in free exploratory testing, Menditect ensures complete testing hygiene through structured Execution Plans:

The Universal Execution Plan Mandate: Before executing any test via execute-testcase, the AI writes a complete, versioned Execution Plan (EP_<Name>.md) to disk containing the test scope, mock parameters, boundary variations, and expected assertions.
auto_execute (Default / Recommended): The AI writes the plan to disk and triggers execution in the very same turn. You get instant test feedback (< 3 seconds total roundtrip) without manual approval pauses. Because the test plan is stored on disk, you can promote it to a permanent MTA test case at any time (PAT-57, PAT-106).
prompt_approval: The AI writes the draft plan and halts at Checkpoint 1, requiring you to explicitly reply "Proceed" before it contacts the plugin MCP server.

Key Request Safeguards in `TCEX_RQ`

ExecutorUsername: "MxAdmin": Provides the execution user context to the Mendix runtime. (Note: If MxAdmin is not present in your Mendix user database, you can specify a different username—such as Admin or a designated test user—in your AGENTS.md directives).
ApplySecurityExecutor: "NONE": Allows isolated unit testing without requiring active browser session logins.
RollbackTcseAfterExecution: "Yes": Guarantees test operations never leave dirty data in your local database.
TCEX_RQ_AttributeValueRun: Injects mock attributes directly into memory before executing the microflow.

Maintenance and Useful Commands Reference

Task	Variant 1: MAIA	Variant 2: Agentic Workspace
Verify Setup	Check MAIA MCP server status indicator in Studio Pro	Run `npm run verify` in terminal
Update Skills	Update `Menditect_AgenticTestSkills` via Marketplace	Run `npm run update:skills`
Re-index Model	Automatic (MAIA reads live Studio Pro model)	Run `./mxcli -c "REFRESH CATALOG FULL FORCE;"`
Check for Tool Updates	Check Studio Pro Marketplace updates	Run `npm run update:check`

Troubleshooting

1. HTTP 401 Unauthorized from `MTA_plugin`

Cause: The MCP access token configured in your IDE / MAIA does not match Studio Pro.
Solution: Ensure PLUGIN_MCP_TOKEN in your .env (or MAIA MCP header) is set to Bearer <YourToken>, matching MtaPluginModule.McpServerAccessToken.

2. Connection Refused (`http://localhost:8081/plugin/mcp`)

Cause: The Mendix application is not running or the MCP server is disabled.
Solution:
1. Make sure your app is running in Studio Pro (F5).
2. Verify that constant MtaPluginModule.EnableMcpServer is set to True.
3. If your Mendix app runs on a custom port (e.g. 8080), change the port in your URL to http://localhost:8080/plugin/mcp.

3. Java Exception: `Executor Username or Executor UserRoles need to be given`

Cause: The execution payload omitted the execution user, or the configured user does not exist in the database.
Solution: The Menditect skills default to "ExecutorUsername": "MxAdmin" and "ApplySecurityExecutor": "NONE". If MxAdmin is not present in your application, set your project's active administrator or test user (e.g. ExecutorUsername: "Admin") in your AGENTS.md file.

4. Java Runtime Errors after installing / updating MTA Plugin

Cause: Leftover or duplicate MTA Plugin .jar files in the project library folder after importing or updating the module.
Solution:
1. Open your local Mendix project directory in your file explorer.
2. Navigate to the userlib/ directory and remove any older or conflicting MTA Plugin .jar files (e.g., mta-plugin-*.jar).
3. In Mendix Studio Pro, go to App > Clean Deployment Directory (or Project > Clean Deployment Directory).
4. Restart and run your Mendix application from Studio Pro (F5).

Note: Upgrading to cloud automated test suites: If you wish to create persistent test suites, run Playwright Frontend UI tests, or integrate with CI/CD deployment pipelines, explore the full MTA Platform options at menditect.com.

Choose Your Setup Path​

Common Step: Install and Configure the MTA Plugin in Studio Pro​

1. Download and Import the MTA Plugin Module​

2. Configure MTA Plugin Constants​

3. Verify Startup Microflow​

4. Start Your Application Locally​

Variant 1: Setup in Mendix MAIA (Studio Pro AI Assistant)​

1. Prerequisites​

2. Download the Menditect Agentic Test Skills Module​

3. Configure MAIA Context and Directives (AGENTS.md)​

4. Connect MAIA to the Local MTA Plugin MCP Server​

5. Execute an Exploratory Test in MAIA​

Variant 2: Setup via Agentic Test Workspace (External AI IDE)​

Why Use the Agentic Test Workspace?​

1. Prerequisites​

2. Create and open your workspace directory​

3. Clone the repository​

4. Go to agentic-test-workspace directory​

5. Run the Setup Wizard​

6. Open Your AI IDE and Execute Your First Test​

How Exploratory Test Execution Works​

Execution Strategy & Plan Governance (exploratory_execution_mode)​

Key Request Safeguards in TCEX_RQ​

Maintenance and Useful Commands Reference​

Troubleshooting​

1. HTTP 401 Unauthorized from MTA_plugin​

2. Connection Refused (http://localhost:8081/plugin/mcp)​

3. Java Exception: Executor Username or Executor UserRoles need to be given​

4. Java Runtime Errors after installing / updating MTA Plugin​

Choose Your Setup Path

Common Step: Install and Configure the MTA Plugin in Studio Pro

1. Download and Import the MTA Plugin Module

2. Configure MTA Plugin Constants

3. Verify Startup Microflow

4. Start Your Application Locally

Variant 1: Setup in Mendix MAIA (Studio Pro AI Assistant)

1. Prerequisites

2. Download the Menditect Agentic Test Skills Module

3. Configure MAIA Context and Directives (`AGENTS.md`)

4. Connect MAIA to the Local MTA Plugin MCP Server

5. Execute an Exploratory Test in MAIA

Variant 2: Setup via Agentic Test Workspace (External AI IDE)

Why Use the Agentic Test Workspace?

1. Prerequisites

2. Create and open your workspace directory

3. Clone the repository

4. Go to agentic-test-workspace directory

5. Run the Setup Wizard

6. Open Your AI IDE and Execute Your First Test

How Exploratory Test Execution Works

Execution Strategy & Plan Governance (`exploratory_execution_mode`)

Key Request Safeguards in `TCEX_RQ`

Maintenance and Useful Commands Reference

Troubleshooting

1. HTTP 401 Unauthorized from `MTA_plugin`

2. Connection Refused (`http://localhost:8081/plugin/mcp`)

3. Java Exception: `Executor Username or Executor UserRoles need to be given`

4. Java Runtime Errors after installing / updating MTA Plugin