Skip to content

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 NEO uses 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 to NEO'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 the NEO template and the ones lippia-neo-bootstrap-stack generates, 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.83 and mcp-atlassian@0.23.1 instead 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.json in the project root, even if your assistant uses a different configuration file (Copilot, Codex, Cursor…). The NEO skills read JIRA_URL / AZURE_DEVOPS_ORG_URL from 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:

  1. Creates .mcp.json in the project root from the template, if it doesn't exist yet.
  2. Checks that .mcp.json is in .gitignore.
  3. 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.
  4. Never shows the token on screen.
  5. 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.json and 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-session skill: 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-stack creates 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_expired in qa-stack.yaml), the run stops asking you to re-capture it, or waits for you to log in by hand if you chose refresh.

5. Security: tokens never go into git

  • .mcp.json contains 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.json ended 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 with env_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: true in Jira and the Work Items → Read permission in Azure DevOps.

6. Check that it's working

Regardless of the client:

  1. Restart the assistant (or reload the window) after changing the configuration.
  2. 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.
  3. 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-studio is 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)