Volver al índice

Conectar Claude Code

Quiero …

… dejar que Claude Code lea y cambie las tareas de este espacio de trabajo, para empezar una tarea desde tu terminal y pasarla a pruebas al terminar.

Antes de empezar

  • Necesitas una clave de API de este espacio de trabajo, consulta «Crear y revocar claves de API». Elige solo los tableros que Claude Code necesita.
  • Los permisos de la clave deciden qué puede hacer Claude Code. Solo lectura lee. Lectura y escritura además crea y cambia tareas, rellena las pruebas y comenta. Para eliminar tareas hace falta Acceso total.
  • Las claves de API necesitan el plan Ultra de la persona Propietario o Admin que las crea, y están en beta.
  • Las tareas, los comentarios y los bugs los escriben personas de tu espacio de trabajo. Una tarea podría contener instrucciones dirigidas a una IA. Da a la clave los menos tableros y permisos posibles, y revisa lo que Claude Code va a hacer.

Así se hace

  1. Crea una clave y cópiala. Para pasar tareas a pruebas, elige Lectura y escritura.
  2. Guarda la clave en la variable de entorno ZEITLICHT_API_KEY, por ejemplo con export ZEITLICHT_API_KEY=zlk_… en el perfil de tu shell, o con la línea de comandos de tu gestor de contraseñas. Nunca escribas la clave en un archivo de tu repositorio.
  3. Para conectar un proyecto, crea en su carpeta raíz el archivo .mcp.json con este contenido: {"mcpServers": {"zeitlicht": {"type": "http", "url": "https://start.zeitlicht.app/api/mcp", "headers": {"Authorization": "Bearer ${ZEITLICHT_API_KEY}"}}}}. El archivo solo contiene el nombre de la variable, no la clave. Puedes hacer commit de él, y cada persona del equipo usa su propia clave.
  4. Para conectar todos tus proyectos, ejecuta en la terminal claude mcp add --transport http --scope user zeitlicht https://start.zeitlicht.app/api/mcp --header "Authorization: Bearer $ZEITLICHT_API_KEY". Claude Code guarda entonces la clave en sus ajustes en tu ordenador.
  5. Inicia Claude Code en el proyecto. Con .mcp.json, Claude Code pregunta una vez si debe usar el servidor. Acepta. /mcp muestra zeitlicht como conectado.
  6. Pregunta con tus propias palabras, por ejemplo «¿Qué tareas de Zeitlicht tengo asignadas?» o «¿Qué necesita la tarea 3f2a9c1e?». Claude Code elige las herramientas, como search_tasks y get_task. Puedes nombrar una tarea por su ID, su ID corto o su enlace. Antes de una herramienta que cambia algo, Claude Code te pide permiso.
  7. Para empezar una tarea, escribe /mcp__zeitlicht__start_task seguido del ID corto o del enlace de la tarea. Claude Code carga la tarea, la resume y propone un nombre de rama como 3f2a9c1e-login-fix. Pon el ID corto en los mensajes de commit y en los títulos de los pull requests, para poder asociarlos después a la tarea.
  8. Cuando termines, escribe /mcp__zeitlicht__handoff_to_testing seguido del ID corto y, si quieres, los correos de quienes prueban separados por comas y el ID de una columna como Test. Claude Code escribe instrucciones de prueba a partir de tus cambios y llama a request_testing: las pruebas se activan, las instrucciones aparecen en la tarea, se añaden las personas que prueban, que reciben un aviso en su actividad, y la tarea pasa a esa columna.

El resultado

Claude Code lee las tareas de los tableros que permite la clave y, con permisos de escritura, las crea y cambia, rellena las pruebas, informa de bugs y comenta, en tu nombre. Cada solicitud aparece en el registro de accesos de la clave.

Preguntas frecuentes

¿Qué herramientas recibe Claude Code?

Con cualquier clave: whoami, list_boards, get_board, list_members, list_tags, list_topics, search_tasks, get_task, get_task_history, list_comments y list_bugs. Con Lectura y escritura además create_task, update_task, move_task, add_checklist_items, update_checklist_item, remove_checklist_item, create_tag, create_topic, add_web_link, remove_web_link, request_testing, update_testing, disable_testing, set_my_verdict, report_bug, update_bug_status, add_comment y delete_comment. delete_task necesita Acceso total. Claude Code solo ve las herramientas que permite la clave. create_tag y create_topic necesitan además una clave para todos los tableros; una clave para tableros seleccionados recibe all-boards-required, y list_members no le muestra correos electrónicos.

¿Quién figura cuando Claude Code cambia una tarea?

Tú, la persona que creó la clave, con el nombre de la clave al lado. Los comentarios y bugs también se escriben en tu nombre. Claude Code solo puede editar y eliminar comentarios escritos así o por ti.

/mcp muestra zeitlicht con error. ¿Qué hago?

Normalmente la clave es incorrecta, caducó o fue revocada, o ZEITLICHT_API_KEY no está definida en la terminal desde la que iniciaste Claude Code. Busca la clave en Claves de API. En la terminal, curl -H "Authorization: Bearer $ZEITLICHT_API_KEY" https://start.zeitlicht.app/api/v1/me muestra el espacio de trabajo de la clave, o por qué se rechaza.

¿Funciona en Claude Desktop o en claude.ai?

Todavía no. Se conectan sin tu clave en una cabecera y necesitan un inicio de sesión, que llegará en una versión posterior.

¿Puede Claude Code ver otros espacios de trabajo?

No. Una clave pertenece a un solo espacio de trabajo y solo ve los tableros elegidos para ella. Para un segundo espacio de trabajo, crea allí una clave y añade un segundo servidor con otro nombre, como zeitlicht-team.

Temas relacionados