Conectar con Claude Code

Esta es la integracion central de Almirant. Al conectar tu IDE con Almirant via MCP (Model Context Protocol), la IA puede leer tus tareas, implementar codigo, mover work items entre columnas y crear pull requests -- todo sin salir del editor.

Que es MCP y por que conectar

MCP (Model Context Protocol) es un protocolo abierto que permite a herramientas de IA (como Claude Code o Cursor) comunicarse con servicios externos de forma bidireccional. Cuando conectas Almirant via MCP:

• La IA lee tus work items, boards y sprints directamente
• La IA actualiza el estado de las tareas al implementar
• La IA crea nuevos work items cuando detecta subtareas
• La IA accede al contexto del proyecto (tech stack, descripcion, objetivos)

Requisitos

Antes de empezar, asegurate de tener:

• Claude Code instalado -- Instrucciones de instalacion
• Un proyecto creado en Almirant -- Crear tu primer proyecto
• Una API Key de Almirant -- La generaremos en el siguiente paso

Paso 1: Generar una API Key

1. En Almirant, accede a Settings desde el menu lateral
2. Navega a la seccion API Keys
3. Haz clic en Crear API Key
4. Dale un nombre descriptivo (por ejemplo, "Claude Code - Laptop trabajo")
5. Copia la API Key generada

Guarda tu API Key

La API Key solo se muestra una vez al crearla. Copiala y guardala en un lugar seguro. Si la pierdes, tendras que generar una nueva.

Paso 2: Obtener el Project ID

Necesitas el ID del proyecto al que quieres conectar la IA. Hay dos formas de obtenerlo:

Opcion A: Desde la URL

Abre tu proyecto en Almirant y copia el UUID que aparece en la URL del navegador:

https://almirant.ai/projects/a1b2c3d4-e5f6-7890-abcd-ef1234567890
                              └──────────── este es tu projectId ────────────┘

Opcion B: Desde la herramienta MCP

Si configuras la conexion sin projectId, puedes usar la herramienta list_projects para ver todos tus proyectos y sus IDs.

Paso 3: Configurar .mcp.json

Crea o edita el archivo .mcp.json en la raiz de tu repositorio:

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=<tu-project-id>",
      "headers": {
        "Authorization": "Bearer <tu-api-key>"
      }
    }
  }
}

Reemplaza los valores:

Placeholder	Valor
<tu-project-id>	El UUID del proyecto obtenido en el Paso 2
<tu-api-key>	La API Key generada en el Paso 1

Ejemplo con valores reales:

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "headers": {
        "Authorization": "Bearer alm_k7x9m2p4q8r1..."
      }
    }
  }
}

Archivo .mcp.json en el repositorio

Puedes incluir el .mcp.json en tu repositorio para que todo el equipo comparta la misma configuracion. Si lo haces, anade la API Key como variable de entorno en lugar de incluirla directamente en el archivo.

Paso 4: Verificar la conexion

Abre Claude Code en tu terminal y verifica que la conexion funciona:

1. Inicia Claude Code en el directorio del proyecto donde creaste .mcp.json
2. Pide a Claude que liste tus proyectos:

> Lista mis proyectos de Almirant

Si la conexion es correcta, Claude respondera con el listado de proyectos. Si tienes projectId configurado, mostrara los detalles del proyecto especifico.

Herramientas MCP disponibles tras la conexion:

Herramienta	Descripcion
list_projects	Lista los proyectos disponibles
list_boards	Lista los boards del proyecto
list_work_items	Lista los work items con filtros
create_work_item	Crea un nuevo work item
update_work_item	Actualiza un work item existente
list_sprints	Lista los sprints del proyecto

Configuracion para Cursor

La configuracion para Cursor es identica. La diferencia esta en la ubicacion del archivo de configuracion:

Cursor utiliza el mismo formato .mcp.json. Coloca el archivo en la raiz de tu proyecto o en la configuracion global de Cursor segun la documentacion de tu version.

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=<tu-project-id>",
      "headers": {
        "Authorization": "Bearer <tu-api-key>"
      }
    }
  }
}

Solucion de problemas

La conexion falla o no responde

1. Verifica la URL -- Asegurate de que la URL es https://api.almirant.ai/mcp (no https://almirant.ai/mcp)
2. Comprueba la API Key -- Genera una nueva si no estas seguro de que la actual es correcta
3. Revisa el formato JSON -- Un error de sintaxis en .mcp.json impedira la conexion

"Unauthorized" o "Invalid API Key"

• La API Key puede haber sido revocada o haber expirado
• Ve a Settings > API Keys en Almirant y genera una nueva
• Actualiza el valor en tu .mcp.json

"Project not found"

• Verifica que el projectId en la URL es correcto
• Comprueba que tienes acceso al proyecto con tu cuenta
• Prueba sin projectId y usa list_projects para ver los IDs disponibles

Claude Code no detecta el servidor MCP

• Asegurate de que el archivo .mcp.json esta en la raiz del directorio donde ejecutas Claude Code
• Reinicia Claude Code despues de crear o modificar el archivo
• Verifica que el JSON es valido (sin comas extra, comillas correctas)

---

Siguiente paso: Tu primer flujo AI -- Implementa una tarea completa usando IA desde tu IDE.