Configure the Jira MCP (and Confluence)
This guide explains, step by step, how to connect Jira (and optionally Confluence) so that NEO reads user stories directly from tickets, without you having to copy them into a file.
| Server name | jira (always use this name) |
| Package | mcp-atlassian, run with uvx mcp-atlassian |
| Type | Local (stdio): it runs on your computer |
| Supported instance | Jira Cloud (https://<sitio>.atlassian.net) |
| Access | Read-only: NEO never modifies tickets |
| Skills that use it | lippia-neo-fetch-user-story, and through it lippia-neo-read-user-story and lippia-neo-resolve-user-story-source when you give them a Jira link |
1. What does NEO do with Jira?
When you give the assistant a key (TECH-123) or a Jira link (https://techstore.atlassian.net/browse/TECH-123):
lippia-neo-resolve-user-story-sourcerecognizes that it's a Jira ticket and checks that the link belongs to your configured site.lippia-neo-fetch-user-storyfetches the complete ticket (all fields and remote links) through thejiraserver.- If the ticket links to Confluence pages, it fetches those too and adds that information, marking where each part came from.
- It returns the story in memory, in the same format as a local story. It doesn't write any file.
lippia-neo-read-user-storyreads it and continues the normal QA flow.
NEOonly reads. It doesn't comment on tickets, change states, or create issues. That's why the recommended configuration usesREAD_ONLY_MODE: "true".
2. Before you start
| You need | Why | How to check it |
|---|---|---|
uv (includes uvx) |
The server is launched with uvx mcp-atlassian. Without uvx, it never starts |
uvx --version |
| An Atlassian account with access to the projects | The server sees exactly what your user sees | Being able to open the ticket in the browser |
| Your site's URL | It goes in JIRA_URL |
It's the URL you use to open Jira |
Install uv if you don't have it:
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
After installing it, open a new terminal and restart the assistant: uv is added to the PATH (%USERPROFILE%\.local\bin on Windows, ~/.local/bin on macOS/Linux) and the assistant has to read it again.
If you don't have uv,
lippia-neo-fetch-user-storytries to install it on its own, based on your operating system, before fetching a Jira ticket. Even so, it's best to have it installed beforehand.
3. Step 1 — Create the API token
The server doesn't use your password: it uses an Atlassian API token.
- Go to id.atlassian.com/manage-profile/security/api-tokens.
- Click Create API token.
- Give it a name that identifies it (for example
NEO - QA) and choose an expiration date. - Copy the token right away: you can't see it again later.
- Store it somewhere safe, for example a password manager. Never paste it into a file that gets pushed to git.
The same token works for Confluence. You don't need to create another one.
4. Step 2 — Tell qa-stack.yaml that your stories come from Jira
paths:
user_stories_storage:
type: cloud
cloud_provider_mcp: jira
local_path: null
# Optional: Jira reading settings
jira:
acceptance_criteria_field: null # e.g. customfield_10034, if your ACs live in a custom field
follow_confluence_links: true # false = don't fetch linked Confluence pages
default_project: TECH # default project prefix (optional)
| Field | What it's for | Default value |
|---|---|---|
user_stories_storage.type: cloud + cloud_provider_mcp: jira |
Tells NEO that your stories come from Jira. Without this, Jira links are rejected |
— |
jira.acceptance_criteria_field |
The field where your team enters the acceptance criteria, if it's a custom field | null: it looks for them in the description and in Confluence |
jira.follow_confluence_links |
Follow the ticket's Confluence links | true |
jira.default_project |
Default project prefix | — |
lippia-neo-bootstrap-stackasks you all of this if you choose "stories in Jira", and it also builds.mcp.jsonfor you (Step 3).
Where are the acceptance criteria?
NEO looks for them in this order and uses the first one it finds:
| Order | Where it looks |
|---|---|
| 1 | The field configured in jira.acceptance_criteria_field |
| 2 | The ticket description: a "Criterios de aceptación" / "Acceptance Criteria" / "AC" heading, a list, or Gherkin blocks (Dado/Cuando/Entonces) |
| 3 | The linked Confluence pages |
| 4 | If it doesn't find anything, it doesn't make them up: it leaves a note so you can fill them in by hand |
To find the field ID (if your team uses a custom field): ask the assistant to fetch a ticket that has the criteria filled in, with all its fields, look for the customfield_* that contains that text, and write its ID in jira.acceptance_criteria_field.
5. Step 3 — Configure the server in your assistant
Base for everyone: .mcp.json in the project root
{
"mcpServers": {
"jira": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-atlassian"],
"env": {
"JIRA_URL": "https://techstore.atlassian.net/",
"JIRA_USERNAME": "your.email@company.com",
"JIRA_API_TOKEN": "<your API token>",
"CONFLUENCE_URL": "https://techstore.atlassian.net/wiki",
"CONFLUENCE_USERNAME": "your.email@company.com",
"CONFLUENCE_API_TOKEN": "<your API token>",
"READ_ONLY_MODE": "true"
}
}
}
}
⚠️ Keep this
.mcp.jsoneven if you use a different assistant. TheNEOskills readJIRA_URLfrom.mcp.jsonfor two things: to check that the link you give belongs to your site, and to build the link back to the ticket in the report. If you use Copilot, Codex, or Claude Desktop (which store their configuration in a different file) and there's no.mcp.jsonwithJIRA_URL,lippia-neo-resolve-user-story-sourceconsiders Jira not configured and stops with "URL de Jira pero el proyecto no está configurado para ese proveedor" ("Jira URL, but the project isn't configured for that provider").
.mcp.json must be in .gitignore: it contains the token. What gets versioned is .mcp.json.template.
Depending on your 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 or open a new session and approve the server |
IDE |
| GitHub Copilot in VS Code | Add the server to .vscode/mcp.json with the servers key, and use inputs for the token |
IDE |
| GitHub Copilot in JetBrains / Visual Studio | Same content with the servers key |
JetBrains · Visual Studio |
| Codex (extension, CLI, or ChatGPT app) | A [mcp_servers.jira] section in ~/.codex/config.toml |
IDE · Terminal |
| Cursor | Copy the block as is into .cursor/mcp.json |
IDE |
| Claude Desktop (chat) | Copy the block, without type, into claude_desktop_config.json and restart the app |
Desktop |
| ChatGPT (regular chat) | ❌ It doesn't work: it only accepts remote servers. Use Codex | Desktop |
Example for Copilot in VS Code (.vscode/mcp.json):
{
"inputs": [
{ "id": "jira-token", "type": "promptString", "description": "API token de Atlassian", "password": true }
],
"servers": {
"jira": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-atlassian"],
"env": {
"JIRA_URL": "https://techstore.atlassian.net/",
"JIRA_USERNAME": "your.email@company.com",
"JIRA_API_TOKEN": "${input:jira-token}",
"CONFLUENCE_URL": "https://techstore.atlassian.net/wiki",
"CONFLUENCE_USERNAME": "your.email@company.com",
"CONFLUENCE_API_TOKEN": "${input:jira-token}",
"READ_ONLY_MODE": "true"
}
}
}
}
Example for Codex (~/.codex/config.toml):
[mcp_servers.jira]
command = "uvx"
args = ["mcp-atlassian"]
[mcp_servers.jira.env]
JIRA_URL = "https://techstore.atlassian.net/"
JIRA_USERNAME = "your.email@company.com"
JIRA_API_TOKEN = "<your API token>"
CONFLUENCE_URL = "https://techstore.atlassian.net/wiki"
CONFLUENCE_USERNAME = "your.email@company.com"
CONFLUENCE_API_TOKEN = "<your API token>"
READ_ONLY_MODE = "true"
With a command, in Claude Code CLI:
claude mcp add --transport stdio --scope project \
--env JIRA_URL=https://techstore.atlassian.net/ \
--env JIRA_USERNAME=your.email@company.com \
--env JIRA_API_TOKEN=<your API token> \
--env CONFLUENCE_URL=https://techstore.atlassian.net/wiki \
--env CONFLUENCE_USERNAME=your.email@company.com \
--env CONFLUENCE_API_TOKEN=<your API token> \
--env READ_ONLY_MODE=true \
jira -- uvx mcp-atlassian
6. Confluence (optional)
Confluence uses the same jira server: you only need to add three keys to its env.
| Key | Value |
|---|---|
CONFLUENCE_URL |
The Jira URL plus /wiki: https://techstore.atlassian.net/wiki |
CONFLUENCE_USERNAME |
The same email as JIRA_USERNAME |
CONFLUENCE_API_TOKEN |
The same token as JIRA_API_TOKEN |
- It's optional and doesn't block anything: if Confluence isn't configured, a page fails, or the ticket doesn't link to any,
NEOcontinues with Jira only and records it as a warning. NEOlooks for Confluence links in the description, in the custom fields, and in the ticket's remote links.- To turn it off even if it's configured:
jira.follow_confluence_links: falseinqa-stack.yaml.
⚠️ Write the full values, without references to other keys. Defining
CONFLUENCE_URLas"${JIRA_URL}wiki", or the token as"${JIRA_API_TOKEN}", doesn't work: the server doesn't replace those references between keys in the same block and fails withInvalid URL: No scheme supplied. Write the full URL, email, and token in each key.
7. Check that it works
- Restart the assistant (or reload the window). Servers are read at startup.
- Open the server list (
/mcpin Claude Code or Codex, MCP: List Servers in VS Code…) and confirm thatjirashows as connected. - Try it with a real ticket:
/lippia-neo-fetch-user-story https://techstore.atlassian.net/browse/TECH-123
It should return the ticket's title, description, and acceptance criteria, with the source of each section (Jira or Confluence).
8. Common problems (and what to do)
| What you see | Why it can happen | What to do |
|---|---|---|
❌ Jira MCP no está disponible en este entorno |
The jira server isn't configured or didn't start |
Review Step 3 and restart the assistant |
The jira server shows as Failed |
uvx is missing, or the assistant can't find it in the PATH |
Install uv, open a new terminal, and restart the assistant |
| 401 / unauthorized error | The password was used instead of an API token, the token expired, or JIRA_USERNAME isn't the account's email |
Create a new token and check the email |
| The ticket "doesn't exist" | Your user doesn't have permission on that project, or the key is wrong | Open the ticket in the browser with your user |
🛑 URL de Jira pero el proyecto no está configurado para ese proveedor |
cloud_provider_mcp: jira is missing from qa-stack.yaml, or there's no jira server in .mcp.json |
Complete Step 2 and the base .mcp.json from Step 3 |
🛑 La URL apunta a una instancia de Jira distinta a la configurada |
The link belongs to another Atlassian site | Use a link from your site or fix JIRA_URL |
No pude resolver la clave del issue |
The reference doesn't contain a valid key (PROYECTO-123, in uppercase) |
Give the key or the /browse/<CLAVE> link |
Invalid URL: No scheme supplied |
CONFLUENCE_URL or the token were defined with ${...} |
Write the full values (section 6) |
| It doesn't fetch Confluence | /wiki is missing from CONFLUENCE_URL, the Confluence keys aren't there, or follow_confluence_links: false |
Review section 6 |
| The acceptance criteria come out empty | They're in a custom field that NEO doesn't know about |
Configure jira.acceptance_criteria_field (section 4) |
| You added the server but it doesn't appear | The assistant wasn't restarted | VS Code: Developer: Reload Window · CLI: open a new session · Claude Desktop: quit the app completely |