API e integraciones
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 lecturalee.Lectura y escrituraademás crea y cambia tareas, rellena las pruebas y comenta. Para eliminar tareas hace faltaAcceso total. - Las claves de API necesitan el plan Ultra de la persona
PropietariooAdminque 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
- Crea una clave y cópiala. Para pasar tareas a pruebas, elige
Lectura y escritura. - Guarda la clave en la variable de entorno
ZEITLICHT_API_KEY, por ejemplo conexport 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. - Para conectar un proyecto, crea en su carpeta raíz el archivo
.mcp.jsoncon 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. - 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. - Inicia Claude Code en el proyecto. Con
.mcp.json, Claude Code pregunta una vez si debe usar el servidor. Acepta./mcpmuestrazeitlichtcomo conectado. - 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_tasksyget_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. - Para empezar una tarea, escribe
/mcp__zeitlicht__start_taskseguido del ID corto o del enlace de la tarea. Claude Code carga la tarea, la resume y propone un nombre de rama como3f2a9c1e-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. - Cuando termines, escribe
/mcp__zeitlicht__handoff_to_testingseguido 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 arequest_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.