kanban/docs/INSTALL_CLAUDE_MCP.md

Prompt para instalar el MCP del kanban en Claude Code

Este documento esta escrito para Claude, no para un humano. Pegalo en tu sesion de Claude Code junto con tu URL y tu token, y Claude registrara el MCP server kanban por ti, verificara la conexion y te dira como invocarlo.

---

Contexto

El kanban (https://github.com/... — repo interno) expone un endpoint MCP Streamable HTTP en /mcp con autenticacion Bearer por usuario. Cada usuario genera su propio token en la UI ("avatar menu → MCP tokens → Generar"). El token cifrado no se recupera: si se pierde, hay que generar otro y revocar el anterior.

El MCP server expone 14 tools para gestionar el board:

Tool	Que hace
list_board	Lista columnas y tarjetas
find_cards	Busca por texto/columna/solicitante
create_card / update_card / delete_card	CRUD de tarjetas
move_card	Mueve tarjeta a otra columna
assign_card	Asigna o desasigna usuario
card_history	Cambios historicos de una tarjeta
create_column / update_column / rename_column / delete_column / reorder_columns	Admin de columnas
list_users	Lista usuarios disponibles

---

Datos que necesitas pedir al usuario (o que recibes con el prompt)

• MCP_URL: URL completa del endpoint, por ejemplo http://192.168.1.50:5180/mcp. Suele ser el mismo host:puerto donde el usuario abre el kanban en el navegador + sufijo /mcp.
• MCP_TOKEN: token que empieza por kmcp_ seguido de 64 caracteres hex. El usuario lo copio del modal "MCP tokens".

Si el usuario no te ha dado uno o ambos, pidelo antes de continuar. NO inventes valores ni uses placeholders.

---

Pasos que tienes que ejecutar

1. Comprobar prerequisitos

claude --version
claude mcp list 2>&1 | head

Si claude no esta en el PATH, indica al usuario que instale Claude Code antes de continuar (no intentes instalarlo tu).

2. Registrar el MCP server

claude mcp add kanban \
  --transport http \
  --header "Authorization: Bearer ${MCP_TOKEN}" \
  -- ${MCP_URL}

Notas:

• Si ya existe un MCP kanban previo, primero claude mcp remove kanban y luego registra el nuevo. NO intentes editarlo en place.
• Si el comando devuelve error sobre --transport, comprueba que la version de Claude Code soporta MCP HTTP (>= 2.0.0). En versiones antiguas usa mcp-remote como bridge:

  claude mcp add kanban -- npx -y mcp-remote "${MCP_URL}" --header "Authorization: Bearer ${MCP_TOKEN}"
  

3. Verificar conexion

claude mcp list

Tiene que aparecer una linea como:

kanban  http  ✓ connected

Si aparece ✗ failed o un error de conexion, comprueba:

• Que el host del kanban es accesible desde esta maquina (curl -s -o /dev/null -w '%{http_code}\n' ${MCP_URL} debe devolver 405 — es POST-only).
• Que el token no caduco ni fue revocado.
• Que la URL termina exactamente en /mcp (sin barra final).

4. Probar una llamada real

claude -p "Usa la tool mcp__kanban__list_board y dime cuantas columnas tiene mi tablero y cuantas tarjetas hay en total." \
  --allowed-tools mcp__kanban__list_board

Output esperado: un resumen en lenguaje natural con el numero de columnas y tarjetas. Si Claude responde "no tengo acceso a esa tool" o "MCP no esta configurado", vuelve al paso 2.

5. Resumir al usuario

Cuando termines, dile al usuario:

• Si la conexion esta OK y el smoke test paso.
• Que tools tiene disponibles.
• Como invocarlas en futuras sesiones (por ejemplo: "crea una tarjeta para revisar el reporte mensual" o "muevela a la columna Doing").
• Como revocar el token si pierde el control de esta maquina.

---

Errores frecuentes

Sintoma	Causa probable	Accion
claude mcp add no acepta --transport http	Version vieja de Claude Code	Usar mcp-remote (ver paso 2).
connection refused	El kanban no esta corriendo o el puerto cambio	Confirmar con el usuario que abre el kanban en el navegador.
401 unauthorized	Token mal copiado o revocado	Generar nuevo token en la UI, repetir paso 2.
405 Method Not Allowed en smoke test	URL apuntando a un GET en vez de POST	El endpoint es POST-only; el flujo de claude mcp lo gestiona, pero un curl manual con GET fallara.
Tools no aparecen tras instalar	Sesion de Claude Code cacheo la config vieja	Cierra y vuelve a abrir Claude Code.

---

Que NO hacer

• No escribas el token en plain text en ningun archivo del repositorio del usuario, ni en logs, ni en commits, ni en mensajes que persistan.
• No intentes "probar" el token llamando al endpoint con curl y pegandolo visible — solo usa el comando claude mcp add.
• No modifiques ~/.claude.json a mano; usa siempre claude mcp add/remove.
• No expongas el endpoint /mcp a redes mas amplias que las del usuario sin consultarle.
• No crees, modifiques ni borres tarjetas durante el smoke test salvo que el usuario lo pida explicitamente. Usa solo list_board para validar.

---

Si algo no esta claro

Pidele al usuario:

• El URL exacto que abre en el navegador para usar el kanban (sin /mcp; lo añades tu).
• El token recien generado (NO uno viejo).
• La version de Claude Code (claude --version).
• El SO en el que esta (uname -a o, en Windows, ver).

Con eso puedes terminar la instalacion en menos de un minuto.