Configure the MCPs
This section explains how to connect the MCP servers that NEO uses to your AI assistant, whether you work from a code editor (VS Code, JetBrains, Visual Studio, Cursor), from a desktop app (Claude Desktop, ChatGPT Desktop, GitHub Copilot app), or from the terminal.
| Where you work | Guide |
|---|---|
| A code editor with the assistant's extension (Claude Code, GitHub Copilot, Codex, Cursor) | Configure MCP in the IDE |
| A desktop app (Claude Desktop, ChatGPT Desktop, GitHub Copilot app) | Configure MCP in desktop apps |
| The terminal (Claude Code CLI, Codex CLI, GitHub Copilot CLI) | Configure MCP in the terminal |
There is also one guide for each user story provider, with the step-by-step process to get the token, the complete configuration, and how to load it into each tool:
| Provider | Guide |
|---|---|
| Jira (and Confluence) | Configure the Jira MCP |
| Azure DevOps (Azure Boards) | Configure the Azure DevOps MCP |
And one guide for the Katalon Studio test framework, whose MCP server creates and runs the tests inside the Katalon project:
| Framework | Guide |
|---|---|
| Katalon Studio | Configure the Katalon Studio MCP |
1. What is an MCP?
An MCP (Model Context Protocol) is a standard "plug" that gives the AI assistant access to an external tool: a browser, Jira, Azure DevOps, and so on. The assistant doesn't have those capabilities on its own. It gets them by connecting to an MCP server, a small program that runs on your computer (or on the internet) and exposes tools such as browser_navigate or jira_get_issue.
Analogy: the assistant is the person doing the work; each MCP server is a tool you lend them. If you don't lend them the browser, they can't open the application to test it.
There are two types of MCP servers:
| Type | How it works | Example |
|---|---|---|
Local (stdio) |
The assistant launches a program on your computer with a command (npx, uvx) |
playwright, jira, azure-devops, neo-docs |
| Remote (HTTP) | The assistant connects to a URL | katalon-studio (published by Katalon Studio on your computer) and cloud connectors |
Important: almost all the servers
NEOuses are local, so they only work in clients that can launch local servers. Some clients, such as the ChatGPT chat, only accept cloud remote servers and cannot connect toNEO's, which depend on your computer. Each guide covers this in detail.
2. Which MCP servers does NEO use?
| Server | Package | What NEO uses it for |
Skills that need it | Required? |
|---|---|---|---|---|
playwright |
@playwright/mcp |
Open a real browser, navigate the app, click, and take screenshots | lippia-neo-run-manual-testing, lippia-neo-reproduce-bug, lippia-neo-run-exploratory-session, lippia-neo-discover-exploratory-areas |
Yes, to explore the app live |
jira |
mcp-atlassian |
Read user stories from Jira and pages from Confluence | lippia-neo-fetch-user-story (and lippia-neo-read-user-story when you give it a Jira link) |
Only if your stories are in Jira · guide |
azure-devops |
@tiberriver256/mcp-server-azure-devops |
Read work items from Azure Boards | lippia-neo-fetch-user-story (and lippia-neo-read-user-story with an Azure link) |
Only if your stories are in Azure DevOps · guide |
katalon-studio |
The MCP server built into Katalon Studio 11.6+ (HTTP) | Create, run and repair the tests (Groovy) inside the Katalon project | lippia-neo-generate-test-suite and lippia-neo-run-and-heal, through the katalon adapter |
Only if test_framework: katalon · guide |
neo-docs |
neo-docs-mcp (run with uvx) |
Query this documentation while you work, with links to each section | None: the assistant uses it to answer questions about NEO |
Optional, recommended · guide |
Keep these names (
playwright,jira,azure-devops,katalon-studio) in every client. They are the ones used by theNEOtemplate and the oneslippia-neo-bootstrap-stackgenerates, so it's best not to change them; that way the configuration is the same across all tools.
What needs to be installed on your computer
| Server | Requirement | How to check it |
|---|---|---|
playwright |
Node.js (includes npx) and the MCP browser |
node -v · npx @playwright/mcp install-browser chrome-for-testing |
jira |
uv (includes uvx), the Python package runner |
uvx --version (if it's missing: docs.astral.sh/uv) |
azure-devops |
Node.js (includes npx) |
node -v |
katalon-studio |
Katalon Studio 11.6+ open, with the suite's project open and the MCP server enabled | See the Katalon guide |
3. The reference configuration
All clients need the same data. The only things that change are the file where you write it and the format. This is the NEO reference configuration (the .mcp.json.template template that lippia-neo-bootstrap-stack uses):
{
"mcpServers": {
"playwright": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@playwright/mcp@latest", "--browser", "chromium"],
"env": {}
},
"katalon-studio": {
"type": "http",
"url": "http://127.0.0.1:33699/mcp/stream",
"headers": {
"Authorization": "Bearer <Katalon MCP server token>"
}
},
"jira": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-atlassian"],
"env": {
"JIRA_URL": "https://your-site.atlassian.net/",
"JIRA_USERNAME": "your.email@company.com",
"JIRA_API_TOKEN": "<Atlassian API token, NOT your password>",
"CONFLUENCE_URL": "https://your-site.atlassian.net/wiki",
"CONFLUENCE_USERNAME": "your.email@company.com",
"CONFLUENCE_API_TOKEN": "<API token de Atlassian>",
"READ_ONLY_MODE": "true"
}
},
"azure-devops": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@tiberriver256/mcp-server-azure-devops"],
"env": {
"AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/your-org",
"AZURE_DEVOPS_AUTH_METHOD": "pat",
"AZURE_DEVOPS_PAT": "<Personal Access Token, scope Work Items → Read>",
"AZURE_DEVOPS_DEFAULT_PROJECT": "<opcional>"
}
}
}
}
Load only the servers you need. If your stories live as .md files in the repository and your framework isn't Katalon, playwright is enough. The katalon-studio block is only used with test_framework: katalon; if the Katalon server doesn't ask for a token, remove headers.
Pinned versions. The template pins
@playwright/mcp@0.0.83andmcp-atlassian@0.23.1instead of@latest, so a package update can't silently break your setup. If you change version, do it in every client alike.If you use Jira or Azure DevOps, always keep this
.mcp.jsonin the project root, even if your assistant uses a different configuration file (Copilot, Codex, Cursor…). TheNEOskills readJIRA_URL/AZURE_DEVOPS_ORG_URLfrom there to validate the links you give them, and without that value they stop. Details in Jira and Azure DevOps.
What each value means
| Value | What it is | Where to get it |
|---|---|---|
JIRA_URL |
Your Jira Cloud site | The URL you use to open Jira (https://<sitio>.atlassian.net/) |
JIRA_USERNAME |
Your Atlassian email | — |
JIRA_API_TOKEN |
An API token (not your password) | id.atlassian.com/manage-profile/security/api-tokens |
CONFLUENCE_* |
The same for Confluence (the skills read the pages linked to the story) | Same site and same kind of token |
READ_ONLY_MODE |
Prevents the server from changing anything in Jira | Leave it as "true": NEO only reads |
AZURE_DEVOPS_ORG_URL |
Your organization's URL | https://dev.azure.com/<organization> |
AZURE_DEVOPS_AUTH_METHOD |
Authentication method | Set "pat" explicitly: if you don't, the server uses a different default method (azure-identity) |
AZURE_DEVOPS_PAT |
Personal Access Token | Azure DevOps → User settings → Personal access tokens, with the Work Items → Read permission |
AZURE_DEVOPS_DEFAULT_PROJECT |
Default project | Optional |
url (Katalon) |
Address of the Katalon Studio MCP server | Katalon Studio shows it in the MCP settings. Don't assume host or port |
headers.Authorization (Katalon) |
MCP server token, only if it asks for one | Katalon Studio, as Bearer <token> |
4. The fastest way: let lippia-neo-bootstrap-stack do it
If you work with Claude Code, you don't need to write anything by hand. When you run lippia-neo-bootstrap-stack and choose that your stories come from Jira or Azure DevOps, or that the framework is Katalon, the skill:
- Creates
.mcp.jsonin the project root from the template, if it doesn't exist yet. - Checks that
.mcp.jsonis in.gitignore. - Asks you for the connection details (for Katalon: the server URL and whether it needs a token) and fills in only the keys that are missing or have a sample value, without overwriting real values.
- Never shows the token on screen.
- Reminds you to restart the assistant, because MCP servers are loaded at startup.
For other clients (Copilot, Codex, Claude Desktop, ChatGPT), take the values from that
.mcp.jsonand convert them to your client's format, following its guide.
Saved session in the Playwright MCP
If the app requires login (stack.auth other than none), lippia-neo-bootstrap-stack also leaves the playwright server ready to explore already logged in, without asking for the credentials:
"args": ["-y", "@playwright/mcp@0.0.83", "--browser", "chromium",
"--isolated",
"--storage-state=.auth/auth-state.json",
"--init-script=.auth/auth-state.session-storage.js"]
| Argument | What it is for |
|---|---|
--isolated |
Required: the Playwright MCP only loads a storage-state in isolated mode |
--storage-state=<path> |
Loads the cookies and localStorage of the saved session (paths.auth_state_file) |
--init-script=<path> |
Re-injects the sessionStorage, which does not travel in the storage-state |
- The session is captured once, by hand, with the
lippia-neo-setup-authenticated-sessionskill: it opens a visible browser, you log in yourself (SSO, 2FA or passkey included) and the skill saves the files. It does not automate or watch that login. - Those two files must exist, or the server fails when opening the browser. That is why
lippia-neo-bootstrap-stackcreates them empty but valid if you haven't captured the session yet. - The session folder (
.auth/by default) goes in.gitignore: it holds valid tokens. - It is the same session that Playwright, Cypress, Lippia and Katalon use.
- If the session expires (
session.on_expiredinqa-stack.yaml), the run stops asking you to re-capture it, or waits for you to log in by hand if you choserefresh.
5. Security: tokens never go into git
.mcp.jsoncontains the literal values (tokens included), which is why it's in.gitignore. The only file that is versioned is.mcp.json.template, with sample values.- If
.mcp.jsonended up being versioned in your repository, remove it from the index:git rm --cached .mcp.json. - In clients that allow it (VS Code with
inputs, Codex withenv_vars, Claude Code with${VARIABLE}), you can avoid writing the token in the file and have it requested or read from the environment instead. Each guide explains how. - Use read-only tokens whenever possible:
READ_ONLY_MODE: truein Jira and the Work Items → Read permission in Azure DevOps.
6. Check that it's working
Regardless of the client:
- Restart the assistant (or reload the window) after changing the configuration.
- Open the client's list of MCP servers (
/mcp, MCP: List Servers, Connectors… depending on the guide) and confirm that each server shows as connected. - Run a simple test:
Using the Playwright MCP, open https://techstore-staging.com and tell me the page title.
Fetch the TECH-123 story from Jira and show me its acceptance criteria.
If any of them fails, check the common problems below and, for Playwright, the Playwright MCP setup guide.
7. Which client supports what
The table covers local servers.
katalon-studiois remote (HTTP): it works in the code clients (Claude Code, Copilot, Codex, Cursor). See the Katalon guide.
| Client | Local servers (what NEO uses) |
Configuration file | Guide |
|---|---|---|---|
| Claude Code (VS Code / CLI / Code tab of the desktop app) | ✅ | .mcp.json (project) or ~/.claude.json (user) |
IDE · Terminal |
| GitHub Copilot in VS Code | ✅ | .vscode/mcp.json |
IDE |
| GitHub Copilot in JetBrains | ✅ | mcp.json (opened from the chat) |
IDE |
| GitHub Copilot in Visual Studio | ✅ | .mcp.json / .vs/mcp.json |
IDE |
| GitHub Copilot CLI | ✅ | ~/.copilot/mcp-config.json or .mcp.json |
Terminal |
| Codex (extension, CLI, and ChatGPT desktop app) | ✅ | ~/.codex/config.toml |
IDE · Terminal · Desktop |
| Cursor | ✅ | .cursor/mcp.json |
IDE |
| Claude Desktop (chat) | ✅ | claude_desktop_config.json |
Desktop |
| GitHub Copilot app (desktop) | ✅ | Uses the configuration from the repository or from Copilot CLI | Desktop |
| ChatGPT (chat and connectors) | ❌ Remote servers only | — | Desktop |
8. Common problems (and what to do)
| What you see | Why it can happen | What to do |
|---|---|---|
| The server doesn't appear in the list | The client wasn't restarted after the configuration changed, or the file is in a different path | Restart and check the path in your client's guide |
Failed to connect / spawn npx ENOENT |
Node.js isn't installed or isn't in the PATH | Install Node.js and restart the client |
The jira server doesn't start |
uv / uvx is missing |
Install uv (docs.astral.sh/uv) |
| Jira returns 401 | The password was used instead of an API token, or the email doesn't match | Generate a new token and check JIRA_USERNAME |
| Azure DevOps doesn't authenticate with the PAT | AZURE_DEVOPS_AUTH_METHOD: "pat" is missing |
Add it |
| The server shows as connected, but the assistant doesn't use its tools | The client isn't in agent mode, or the tools are disabled | See your client's guide (Copilot and Visual Studio have a tool picker) |
Browser "chrome-for-testing" is not installed |
The @playwright/mcp version expects a different browser version |
npx @playwright/mcp@latest install-browser chrome-for-testing |
katalon-studio shows Failed or timeout |
Katalon Studio isn't open, or the handshake (~30 s) exceeds the wait time | Open Katalon Studio and set MCP_TIMEOUT=60000 (see Katalon) |
| The Playwright MCP fails to open the browser with a saved session | The --storage-state or --init-script file is missing or empty (0 bytes) |
Re-capture the session with lippia-neo-setup-authenticated-session or run lippia-neo-bootstrap-stack again |
| The same server appears twice | It's configured in two places at once (user and project) | Keep it in only one (see Incident 2) |