Saltar a contenido

Configurar el MCP de Jira (y Confluence)

Esta guía explica, paso a paso, cómo conectar Jira (y opcionalmente Confluence) para que NEO lea las historias de usuario directamente desde los tickets, sin tener que copiarlas a un archivo.

Nombre del servidor jira (usá siempre este nombre)
Paquete mcp-atlassian, que se ejecuta con uvx mcp-atlassian
Tipo Local (stdio): se ejecuta en tu computadora
Instancia soportada Jira Cloud (https://<sitio>.atlassian.net)
Acceso Solo lectura: NEO nunca modifica tickets
Skills que lo usan lippia-neo-fetch-user-story, y a través de ella lippia-neo-read-user-story y lippia-neo-resolve-user-story-source cuando les pasás un link de Jira

1. ¿Qué hace NEO con Jira?

Cuando le pasás al asistente una clave (TECH-123) o un link de Jira (https://techstore.atlassian.net/browse/TECH-123):

  1. lippia-neo-resolve-user-story-source reconoce que es un ticket de Jira y verifica que el link sea de tu sitio configurado.
  2. lippia-neo-fetch-user-story trae el ticket completo (todos los campos y los links remotos) a través del servidor jira.
  3. Si el ticket enlaza páginas de Confluence, también las trae y suma esa información, marcando de dónde salió cada parte.
  4. Devuelve la historia en memoria, con el mismo formato que una historia local. No escribe ningún archivo.
  5. lippia-neo-read-user-story la lee y sigue el flujo normal de QA.

NEO solo lee. No comenta tickets, no cambia estados y no crea issues. Por eso la configuración recomendada usa READ_ONLY_MODE: "true".


2. Antes de empezar

Necesitás Por qué Cómo verificarlo
uv (trae uvx) El servidor se lanza con uvx mcp-atlassian. Sin uvx, nunca arranca uvx --version
Una cuenta de Atlassian con acceso a los proyectos El servidor ve exactamente lo mismo que ve tu usuario Poder abrir el ticket en el navegador
La URL de tu sitio Se configura en JIRA_URL Es la URL con la que entrás a Jira

Instalar uv si no lo tenés:

# 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

Después de instalarlo, abrí una terminal nueva y reiniciá el asistente: uv se agrega al PATH (%USERPROFILE%\.local\bin en Windows, ~/.local/bin en macOS/Linux) y el asistente tiene que volver a leerlo.

Si no tenés uv, lippia-neo-fetch-user-story intenta instalarlo sola según tu sistema operativo antes de traer un ticket de Jira. Igual conviene dejarlo instalado de antemano.


3. Paso 1 — Crear el API token

El servidor no usa tu contraseña: usa un API token de Atlassian.

  1. Entrá a id.atlassian.com/manage-profile/security/api-tokens.
  2. Hacé clic en Create API token.
  3. Ponele un nombre que lo identifique (por ejemplo NEO - QA) y elegí una fecha de vencimiento.
  4. Copiá el token en ese momento: después no se puede volver a ver.
  5. Guardalo en un lugar seguro, por ejemplo un gestor de contraseñas. Nunca lo pegues en un archivo que se suba a git.

El mismo token sirve para Confluence. No hace falta crear otro.


4. Paso 2 — Indicar en qa-stack.yaml que las historias vienen de Jira

paths:
  user_stories_storage:
    type: cloud
    cloud_provider_mcp: jira
    local_path: null

# Opcional: ajustes de lectura de Jira
jira:
  acceptance_criteria_field: null   # ej. customfield_10034, si tus AC viven en un campo propio
  follow_confluence_links: true     # false = no traer las páginas de Confluence enlazadas
  default_project: TECH             # prefijo de proyecto por defecto (opcional)
Campo Para qué Valor por defecto
user_stories_storage.type: cloud + cloud_provider_mcp: jira Le dice a NEO que las historias vienen de Jira. Sin esto, los links de Jira se rechazan —
jira.acceptance_criteria_field El campo donde tu equipo carga los criterios de aceptación, si es un campo propio null: los busca en la descripción y en Confluence
jira.follow_confluence_links Seguir los links a Confluence del ticket true
jira.default_project Prefijo de proyecto por defecto —

lippia-neo-bootstrap-stack te pregunta todo esto si elegís "historias en Jira", y de paso arma .mcp.json (Paso 3).

¿Dónde están los criterios de aceptación?

NEO los busca en este orden y usa el primero que encuentra:

Orden Dónde busca
1 El campo configurado en jira.acceptance_criteria_field
2 La descripción del ticket: un título "Criterios de aceptación" / "Acceptance Criteria" / "AC", una lista o bloques Gherkin (Dado/Cuando/Entonces)
3 Las páginas de Confluence enlazadas
4 Si no encuentra nada, no los inventa: deja una nota para completarlos a mano

Para averiguar el ID del campo (si tu equipo usa un campo propio): pedile al asistente que traiga un ticket que tenga los criterios cargados con todos sus campos, buscá qué customfield_* contiene ese texto y anotá su ID en jira.acceptance_criteria_field.


5. Paso 3 — Configurar el servidor en tu asistente

Base para todos: .mcp.json en la raíz del proyecto

{
  "mcpServers": {
    "jira": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "JIRA_URL": "https://techstore.atlassian.net/",
        "JIRA_USERNAME": "tu.email@empresa.com",
        "JIRA_API_TOKEN": "<tu API token>",
        "CONFLUENCE_URL": "https://techstore.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "tu.email@empresa.com",
        "CONFLUENCE_API_TOKEN": "<tu API token>",
        "READ_ONLY_MODE": "true"
      }
    }
  }
}

⚠️ Tené este .mcp.json aunque uses otro asistente. Las skills de NEO leen JIRA_URL desde .mcp.json para dos cosas: verificar que el link que pasás sea de tu sitio, y armar el link de vuelta al ticket en el reporte. Si usás Copilot, Codex o Claude Desktop (que guardan la configuración en otro archivo) y no hay .mcp.json con JIRA_URL, lippia-neo-resolve-user-story-source considera que Jira no está configurado y frena con "URL de Jira pero el proyecto no está configurado para ese proveedor".

.mcp.json tiene que estar en .gitignore: lleva el token. Lo que se versiona es .mcp.json.template.

Según tu asistente

Asistente Qué hacer Detalle del formato
Claude Code (VS Code, CLI o pestaña Code de Claude Desktop) Nada más: lee el .mcp.json de arriba. Recargá la ventana o abrí una sesión nueva y aprobá el servidor IDE
GitHub Copilot en VS Code Cargá el servidor en .vscode/mcp.json con la clave servers, y usá inputs para el token IDE
GitHub Copilot en JetBrains / Visual Studio Mismo contenido con la clave servers JetBrains · Visual Studio
Codex (extensión, CLI o app de ChatGPT) Sección [mcp_servers.jira] en ~/.codex/config.toml IDE · Terminal
Cursor Copiá el bloque tal cual a .cursor/mcp.json IDE
Claude Desktop (chat) Copiá el bloque, sin type, a claude_desktop_config.json y reiniciá la app Escritorio
ChatGPT (chat común) ❌ No sirve: solo acepta servidores remotos. Usá Codex Escritorio

Ejemplo para Copilot en 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": "tu.email@empresa.com",
        "JIRA_API_TOKEN": "${input:jira-token}",
        "CONFLUENCE_URL": "https://techstore.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "tu.email@empresa.com",
        "CONFLUENCE_API_TOKEN": "${input:jira-token}",
        "READ_ONLY_MODE": "true"
      }
    }
  }
}

Ejemplo para Codex (~/.codex/config.toml):

[mcp_servers.jira]
command = "uvx"
args = ["mcp-atlassian"]

[mcp_servers.jira.env]
JIRA_URL = "https://techstore.atlassian.net/"
JIRA_USERNAME = "tu.email@empresa.com"
JIRA_API_TOKEN = "<tu API token>"
CONFLUENCE_URL = "https://techstore.atlassian.net/wiki"
CONFLUENCE_USERNAME = "tu.email@empresa.com"
CONFLUENCE_API_TOKEN = "<tu API token>"
READ_ONLY_MODE = "true"

Por comando, en Claude Code CLI:

claude mcp add --transport stdio --scope project \
  --env JIRA_URL=https://techstore.atlassian.net/ \
  --env JIRA_USERNAME=tu.email@empresa.com \
  --env JIRA_API_TOKEN=<tu API token> \
  --env CONFLUENCE_URL=https://techstore.atlassian.net/wiki \
  --env CONFLUENCE_USERNAME=tu.email@empresa.com \
  --env CONFLUENCE_API_TOKEN=<tu API token> \
  --env READ_ONLY_MODE=true \
  jira -- uvx mcp-atlassian

6. Confluence (opcional)

Confluence usa el mismo servidor jira: solo hay que sumar tres claves a su env.

Clave Valor
CONFLUENCE_URL La URL de Jira más /wiki: https://techstore.atlassian.net/wiki
CONFLUENCE_USERNAME El mismo email que JIRA_USERNAME
CONFLUENCE_API_TOKEN El mismo token que JIRA_API_TOKEN
  • Es opcional y no bloquea nada: si Confluence no está configurado, una página falla o el ticket no enlaza ninguna, NEO sigue solo con Jira y lo deja anotado como aviso.
  • NEO busca links de Confluence en la descripción, en los campos personalizados y en los links remotos del ticket.
  • Para desactivarlo aunque esté configurado: jira.follow_confluence_links: false en qa-stack.yaml.

⚠️ Escribí los valores completos, sin referencias a otras claves. Definir CONFLUENCE_URL como "${JIRA_URL}wiki", o el token como "${JIRA_API_TOKEN}", no funciona: el servidor no reemplaza esas referencias entre claves del mismo bloque y falla con Invalid URL: No scheme supplied. Escribí la URL, el email y el token completos en cada clave.


7. Verificar que funciona

  1. Reiniciá el asistente (o recargá la ventana). Los servidores se leen al arrancar.
  2. Abrí la lista de servidores (/mcp en Claude Code o Codex, MCP: List Servers en VS Code…) y confirmá que jira figura conectado.
  3. Probalo con un ticket real:
/lippia-neo-fetch-user-story https://techstore.atlassian.net/browse/TECH-123

Tiene que devolver el título, la descripción y los criterios de aceptación del ticket, con la fuente de cada sección (Jira o Confluence).


8. Problemas comunes (y qué hacer)

Lo que ves Por qué puede pasar Qué hacer
❌ Jira MCP no está disponible en este entorno El servidor jira no está configurado o no arrancó Revisar el Paso 3 y reiniciar el asistente
El servidor jira figura como Failed Falta uvx, o el asistente no lo encuentra en el PATH Instalar uv, abrir una terminal nueva y reiniciar el asistente
Error 401 / no autorizado Se usó la contraseña en vez de un API token, el token venció o JIRA_USERNAME no es el email de la cuenta Crear un token nuevo y revisar el email
El ticket "no existe" Tu usuario no tiene permiso sobre ese proyecto, o la clave está mal Abrir el ticket en el navegador con tu usuario
🛑 URL de Jira pero el proyecto no está configurado para ese proveedor Falta cloud_provider_mcp: jira en qa-stack.yaml, o no hay servidor jira en .mcp.json Completar el Paso 2 y el .mcp.json base del Paso 3
🛑 La URL apunta a una instancia de Jira distinta a la configurada El link es de otro sitio de Atlassian Usar un link de tu sitio o corregir JIRA_URL
No pude resolver la clave del issue La referencia no tiene una clave válida (PROYECTO-123, en mayúsculas) Pasar la clave o el link /browse/<CLAVE>
Invalid URL: No scheme supplied CONFLUENCE_URL o el token se definieron con ${...} Escribir los valores completos (sección 6)
No trae Confluence Falta /wiki en CONFLUENCE_URL, no están las claves de Confluence o follow_confluence_links: false Revisar la sección 6
Los criterios de aceptación salen vacíos Están en un campo personalizado que NEO no conoce Configurar jira.acceptance_criteria_field (sección 4)
Agregaste el servidor pero no aparece El asistente no se reinició VS Code: Developer: Reload Window · CLI: abrir otra sesión · Claude Desktop: cerrar la app por completo