Set up the Katalon Studio MCP
This guide explains how to connect Katalon Studio so that NEO creates, runs and repairs automated tests inside a Katalon project, in Groovy, instead of generating them as files in the repository.
| Server name | katalon-studio (always use this name) |
| Server | The MCP server built into Katalon Studio (11.6 or later). No package to install |
| Type | Remote over HTTP (type: http): Katalon Studio exposes it at a URL, usually on your own computer |
| Authentication | Optional token (Authorization: Bearer <token>) |
| When it is needed | Only if the project uses stack.test_framework: katalon in qa-stack.yaml |
| Skills that use it | lippia-neo-generate-test-suite and lippia-neo-run-and-heal, through the katalon adapter. It is added by lippia-neo-bootstrap-stack |
Unlike the other
NEOservers, this one is not a program the assistant launches (npx/uvx): Katalon Studio publishes it, and the assistant only connects to its URL. That is why Katalon Studio must be open.
1. What does NEO do with Katalon?
With test_framework: katalon there is no tests_dir folder: the suite lives in the Katalon project you have open. NEO manages it through the MCP tools:
| Stage | What it does | MCP tools it uses |
|---|---|---|
Generate (lippia-neo-generate-test-suite) |
Creates one test case per plan case, its test objects (locators), the <US-ID> suite and the session keyword |
writeTestCase, writeWebTestObject, writeRestWebServiceTestObject, writeTestSuite, writeCustomKeyword, listEntityFiles, readFile, searchProject |
Run and heal (lippia-neo-run-and-heal) |
Runs the tests from Katalon Studio, reads the results, diagnoses failures and fixes the tests | executeTest, getTestExecutionStatus, getTestExecutionResults, analyzeTestFailure, stopTestExecution and, to validate broken locators, the webUI* tools |
What Playwright still does
Exploration (scripted execution, exploratory sessions, bug reproduction) still uses the Playwright MCP, also with Katalon. Katalon's navigation is used only when healing, to check a locator in the same engine that runs the test. So a Katalon project needs both servers: playwright and katalon-studio.
Why not use Katalon's navigation to explore? It has no hover, select, keys, file upload, waits, console or network; it does not load the saved session; and it would force Katalon Studio to be open for every exploration. The details are in ADR-028 of the architecture.
2. Before you start
| You need | Why | How to check |
|---|---|---|
| Katalon Studio 11.6 or later | It is the version that ships the built-in MCP server | Help → About Katalon Studio |
| The suite's project open | The MCP works on whichever project is open at that moment | See the project in the Tests Explorer |
| The MCP server enabled | It is off until you turn it on | See Step 1 |
| An active Katalon license | Katalon Studio needs it to run tests | The app opens without asking for activation |
| The Playwright MCP | To explore the app, as with the other frameworks | See the general guide |
3. Step 1 — Enable the MCP server in Katalon Studio
- Open Katalon Studio and the project where the tests will live.
- Go to Katalon Studio's MCP server settings and enable it.
- Note the URL it shows. It looks like this:
http://127.0.0.1:33699/mcp/stream
Don't assume the host or port: they change between installations and the server may be remote. Always copy the URL your Katalon Studio shows. 4. If the server asks for a token, copy it. If it doesn't, no token is needed.
Exact menu names may vary between Katalon Studio versions. If you can't find the option, search for "MCP" in the application settings.
4. Step 2 — Declare the framework in qa-stack.yaml
stack:
test_framework: katalon
language: groovy
# There is no paths.tests_dir: the suite lives in the Katalon project
katalon:
mcp_server: katalon-studio # server name in .mcp.json
test_cases_folder: Test Cases # creates <folder>/<US-ID>/ per story
object_repository_folder: Object Repository
test_suites_folder: Test Suites # one <US-ID> suite per story
browser: CHROME
execution_profile: default # profile holding the GlobalVariables
| Field | What it is for | Default |
|---|---|---|
mcp_server |
Server name in .mcp.json. The URL and token live there, not in this file |
katalon-studio |
test_cases_folder |
Test cases folder. Each story gets its own: <US-ID>/ |
Test Cases |
object_repository_folder |
Test objects folder, under <US-ID>/<Page>/ |
Object Repository |
test_suites_folder |
Suites folder (one per story) | Test Suites |
browser |
Execution browser: CHROME, CHROME_HEADLESS, FIREFOX, FIREFOX_HEADLESS, EDGE_CHROMIUM, SAFARI |
CHROME |
execution_profile |
Katalon profile with the GlobalVariables (BASE_URL, APP_USER, APP_PASSWORD, API_TOKEN_*) |
default |
lippia-neo-bootstrap-stackasks all of this when you pick Katalon as the framework: the server URL, whether it needs a token, the folders, the browser and the profile. It does not ask fortests_dir.
5. Step 3 — Configure the server in your assistant
Base for everyone: .mcp.json at the project root
{
"mcpServers": {
"katalon-studio": {
"type": "http",
"url": "http://127.0.0.1:33699/mcp/stream",
"headers": {
"Authorization": "Bearer <Katalon MCP server token>"
}
}
}
}
| Key | Required? | What it is for |
|---|---|---|
type |
Yes, with the value "http" |
It is a remote server, not a local command |
url |
Yes | The URL Katalon Studio shows (Step 1) |
headers.Authorization |
Only if the server asks for a token | Bearer <token>. If it doesn't ask for a token, delete the whole headers block |
.mcp.json must be in .gitignore if it holds the token. What gets versioned is .mcp.json.template.
By assistant
| Assistant | What to do | Format details |
|---|---|---|
| Claude Code (VS Code, CLI or the Code tab of Claude Desktop) | Nothing else: it reads the .mcp.json above. Reload the window and approve the server |
IDE · Terminal |
| GitHub Copilot in VS Code / JetBrains / Visual Studio | Same content under the servers key |
IDE |
| Codex | A [mcp_servers.katalon-studio] section with url in ~/.codex/config.toml |
IDE · Terminal |
| Cursor | Copy the block to .cursor/mcp.json |
IDE |
| Claude Desktop (chat) and ChatGPT (chat) | ❌ Not the path for NEO. Use the Code tab of Claude Desktop, or Codex |
Desktop |
By command, in Claude Code CLI:
claude mcp add --transport http --scope project katalon-studio \
http://127.0.0.1:33699/mcp/stream \
--header "Authorization: Bearer <token>"
Example for Copilot in VS Code (.vscode/mcp.json), asking for the token on connect:
{
"inputs": [
{ "id": "katalon-token", "type": "promptString", "description": "Katalon MCP token", "password": true }
],
"servers": {
"katalon-studio": {
"type": "http",
"url": "http://127.0.0.1:33699/mcp/stream",
"headers": { "Authorization": "Bearer ${input:katalon-token}" }
}
}
}
Example for Codex (~/.codex/config.toml):
[mcp_servers.katalon-studio]
url = "http://127.0.0.1:33699/mcp/stream"
bearer_token_env_var = "KATALON_MCP_TOKEN" # environment variable holding the token; remove if no token is needed
If you rename the server, remember to update
katalon.mcp_serverinqa-stack.yaml: it must match the name used in.mcp.json.
The initial handshake is slow
The first start of the Katalon MCP takes about 30 seconds. If the assistant shows it as failed to connect or timeout, raise the wait time before opening it:
| System | How |
|---|---|
| Windows (PowerShell) | setx MCP_TIMEOUT 60000 and open a new terminal |
| macOS / Linux | export MCP_TIMEOUT=60000 in your shell profile |
MCP_TIMEOUT is in milliseconds. Then restart the assistant.
6. Step 4 — Prepare the profile with the credentials
The app's credentials do not go in any repository file: the tests read them as GlobalVariables from Katalon's execution profile. The MCP cannot write profiles, so you load them by hand:
- In Katalon Studio: Tests Explorer → Profiles →
<your profile>(defaultby default). - Add only the ones that apply to your setup:
| Variable | When it is needed |
|---|---|
BASE_URL |
Always (it is environment.base_url) |
APP_USER and APP_PASSWORD |
With auth: basic_auth |
API_TOKEN_* |
With auth: api_token |
QA_AUTH_STATE_PATH |
Optional. Absolute path to the repo's saved session (see section 7) |
- Save with
Ctrl+S. ForAPP_PASSWORD, use Tools → Encrypt Text and paste the encrypted value.
If a variable is missing,
lippia-neo-run-and-healdoes not run and tells you which ones are missing (names only, never values). Without them every test would fail withMissingPropertyException: No such property: <VAR> for class: internal.GlobalVariable.
7. The saved session with Katalon
When the app requires login (auth other than none), NEO saves a single session that every tool shares: the Playwright MCP, Playwright, Cypress, Lippia and Katalon. The session lives in paths.auth_state_file (.auth/auth-state.json by default, ignored by git).
| How it is built | What happens |
|---|---|
google_sso (SSO, 2FA, captcha) |
A person logs in by hand, once, using the lippia-neo-setup-authenticated-session skill. NEO never automates or watches that login |
basic_auth |
With session.on_expired: refresh, the first test case logs in with APP_USER / APP_PASSWORD and saves the session; the rest restore it. With fail, it stops and does not log in |
In the Katalon project this becomes two pieces created by lippia-neo-generate-test-suite:
lippia_neo.SavedSession: a Groovy keyword that loads the session into Katalon's browser and, withbasic_auth, saves it after login.Common/open_authenticated_app: a shared precondition that every test calls (WebUI.callTestCase). Depending onauth, it navigates, logs in or restores the session.
What happens when the session expires (session.on_expired)
| Value | What it does |
|---|---|
fail (default) |
Stops with a message: re-capture the session (google_sso) or check the credentials (basic_auth). It never tries to log in |
refresh with google_sso |
The precondition waits for you to log in by hand in Katalon's browser (up to session.refresh_timeout_s, 300 s by default) and saves the new session. When Chrome opens, log in yourself |
refresh with basic_auth |
The precondition logs in on its own with APP_USER / APP_PASSWORD and saves the new session. No action needed |
With refresh and google_sso the browser must be visible: if katalon.browser is *_HEADLESS, NEO uses the visible variant for that run and tells you.
Sharing the session with Playwright
If the Katalon project is not inside the test repository, define QA_AUTH_STATE_PATH (absolute path) in the profile so Katalon and Playwright use the same file. Otherwise the session stays in .auth/ inside the Katalon project: add it to that project's .gitignore.
It is sensitive. The session file holds valid tokens.
NEOdoes not open or show it, and you should not commit it to git either.
The Playwright MCP uses the same session when exploring: see Saved session in the Playwright MCP.
8. Execution rules worth knowing
| Rule | What it means for you |
|---|---|
| One execution at a time | Katalon does not run in parallel: a run's test cases go in series |
| Timing | executeTest waits up to 110 s. For a suite, NEO polls the status, capped at 15 minutes |
| Existing items are never modified | Before creating a test case, NEO looks for duplicates (by <US-ID> and tc<NNN> tags, by name and by content). If one exists, it doesn't create it and tells you; it never modifies an existing test |
| The Object Repository is reused | Before creating a test object, it searches the whole repository for one pointing to the same element with a stable locator (including the ones you recorded with the Web Recorder or Spy) |
Credentials always as GlobalVariable |
Never as literals in the script |
| Locators only in the Object Repository | The script uses findTestObject(...), never a loose XPath or CSS |
| CI | Running outside Katalon Studio requires Katalon Runtime Engine (katalonc) with a license. lippia-neo-bootstrap-ci does not generate Katalon jobs yet |
9. Verify it works
- Open Katalon Studio with the right project and the MCP server enabled.
- Restart the assistant (or reload the window).
- Open the server list (
/mcpin Claude Code or Codex, MCP: List Servers in VS Code…) and confirmkatalon-studioshows as connected. It can take about 30 seconds. - Try it:
With the Katalon MCP, list the test suites of the open project.
It is the same check lippia-neo-run-and-heal does (listEntityFiles on TEST_SUITE). If it answers, the connection is fine.
10. Common problems (and what to do)
| What you see | Why it may happen | What to do |
|---|---|---|
katalon-studio shows as Failed or timeout |
The initial handshake takes ~30 s, or Katalon Studio is not open | Open Katalon Studio and set MCP_TIMEOUT=60000; restart the assistant |
Katalon Studio is not open or its MCP server is not connected |
lippia-neo-run-and-heal couldn't list the test suites |
Open Katalon Studio with the suite's project and check the connection |
| Connection refused / no response | The URL or port isn't your installation's | Copy the URL again from the MCP settings in Katalon Studio |
| 401 / unauthorized | The server asks for a token and it's missing or wrong | Add headers.Authorization: Bearer <token>. If it asks for none, remove headers |
| The MCP works but creates tests in another project | The MCP works on the open project | Open the right project in Katalon Studio and run again |
MissingPropertyException: No such property: <VAR> for class: internal.GlobalVariable |
A variable is missing from the execution profile | Add it in Tests Explorer → Profiles (section 6) |
| Login is requested on every test case | save and restore use different session files |
Check QA_AUTH_STATE_PATH in the profile (or as an environment variable) |
Manual login was not completed |
With session.on_expired: refresh, login wasn't finished in time |
Run again and log in within session.refresh_timeout_s |
| The browser isn't visible and there's nowhere to log in | katalon.browser is *_HEADLESS |
Use the visible browser for that run |
katalon.mcp_server doesn't match the server |
The server was renamed in .mcp.json |
Use the same name in qa-stack.yaml |
The assistant loses Katalon after editing .mcp.json |
Servers load at startup | Restart the assistant |