Skip to content

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 NEO servers, 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

  1. Open Katalon Studio and the project where the tests will live.
  2. Go to Katalon Studio's MCP server settings and enable it.
  3. 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-stack asks 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 for tests_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_server in qa-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:

  1. In Katalon Studio: Tests Explorer → Profiles → <your profile> (default by default).
  2. 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)
  1. Save with Ctrl+S. For APP_PASSWORD, use Tools → Encrypt Text and paste the encrypted value.

If a variable is missing, lippia-neo-run-and-heal does not run and tells you which ones are missing (names only, never values). Without them every test would fail with MissingPropertyException: 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, with basic_auth, saves it after login.
  • Common/open_authenticated_app: a shared precondition that every test calls (WebUI.callTestCase). Depending on auth, 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. NEO does 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

  1. Open Katalon Studio with the right project and the MCP server enabled.
  2. Restart the assistant (or reload the window).
  3. Open the server list (/mcp in Claude Code or Codex, MCP: List Servers in VS Code…) and confirm katalon-studio shows as connected. It can take about 30 seconds.
  4. 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