Skip to content

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):

  1. lippia-neo-resolve-user-story-source recognizes that it's a Jira ticket and checks that the link belongs to your configured site.
  2. lippia-neo-fetch-user-story fetches the complete ticket (all fields and remote links) through the jira server.
  3. If the ticket links to Confluence pages, it fetches those too and adds that information, marking where each part came from.
  4. It returns the story in memory, in the same format as a local story. It doesn't write any file.
  5. lippia-neo-read-user-story reads it and continues the normal QA flow.

NEO only reads. It doesn't comment on tickets, change states, or create issues. That's why the recommended configuration uses READ_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-story tries 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.

  1. Go to id.atlassian.com/manage-profile/security/api-tokens.
  2. Click Create API token.
  3. Give it a name that identifies it (for example NEO - QA) and choose an expiration date.
  4. Copy the token right away: you can't see it again later.
  5. 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-stack asks you all of this if you choose "stories in Jira", and it also builds .mcp.json for 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.json even if you use a different assistant. The NEO skills read JIRA_URL from .mcp.json for 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.json with JIRA_URL, lippia-neo-resolve-user-story-source considers 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, NEO continues with Jira only and records it as a warning.
  • NEO looks 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: false in qa-stack.yaml.

⚠️ Write the full values, without references to other keys. Defining CONFLUENCE_URL as "${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 with Invalid URL: No scheme supplied. Write the full URL, email, and token in each key.


7. Check that it works

  1. Restart the assistant (or reload the window). Servers are read at startup.
  2. Open the server list (/mcp in Claude Code or Codex, MCP: List Servers in VS Code…) and confirm that jira shows as connected.
  3. 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