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):
lippia-neo-resolve-user-story-sourcereconoce que es un ticket de Jira y verifica que el link sea de tu sitio configurado.lippia-neo-fetch-user-storytrae el ticket completo (todos los campos y los links remotos) a través del servidorjira.- Si el ticket enlaza páginas de Confluence, también las trae y suma esa información, marcando de dónde salió cada parte.
- Devuelve la historia en memoria, con el mismo formato que una historia local. No escribe ningún archivo.
lippia-neo-read-user-storyla lee y sigue el flujo normal de QA.
NEOsolo lee. No comenta tickets, no cambia estados y no crea issues. Por eso la configuración recomendada usaREAD_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-storyintenta 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.
- Entrá a id.atlassian.com/manage-profile/security/api-tokens.
- Hacé clic en Create API token.
- Ponele un nombre que lo identifique (por ejemplo
NEO - QA) y elegí una fecha de vencimiento. - Copiá el token en ese momento: después no se puede volver a ver.
- 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-stackte 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.jsonaunque uses otro asistente. Las skills deNEOleenJIRA_URLdesde.mcp.jsonpara 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.jsonconJIRA_URL,lippia-neo-resolve-user-story-sourceconsidera 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,
NEOsigue solo con Jira y lo deja anotado como aviso. NEObusca 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: falseenqa-stack.yaml.
⚠️ Escribí los valores completos, sin referencias a otras claves. Definir
CONFLUENCE_URLcomo"${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 conInvalid URL: No scheme supplied. Escribí la URL, el email y el token completos en cada clave.
7. Verificar que funciona
- Reiniciá el asistente (o recargá la ventana). Los servidores se leen al arrancar.
- Abrí la lista de servidores (
/mcpen Claude Code o Codex, MCP: List Servers en VS Code…) y confirmá quejirafigura conectado. - 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 |