Desarrolladores

Claude y MCP

Claude trabaja en VentionDesk como un miembro del equipo: toma tareas, las implementa e informa del resultado — exactamente con los derechos de la clave que le des. VentionDesk no ejecuta ningún modelo propio para ello y no cobra nada: tú aportas tu propio Claude (Claude Code con tu suscripción de Claude o tu clave de Anthropic).

Hay dos caminos: el servidor MCP — recomendado para Claude Code — y la API directamente, por ejemplo desde tus propios scripts. También funciona sin clave: cada persona conecta Claude, ChatGPT, Cursor o Codex con su propio inicio de sesión — consulta Conectar apps de IA.

1. Crear una clave de agente

Ajustes › Claves de API › «Nueva clave», tipo «Agente»:

Permisos: para trabajar en tareas, projects:read, tasks:read y tasks:write; notes:write si Claude debe crear notas; agent:run si se deben registrar las ejecuciones. Tickets, respuestas a clientes, borradores de facturas y presupuestos, errores, tiempos, indicadores, hoja de ruta e ideas solo los activas si lo quieres expresamente (ver abajo).
Proyectos: todos, o solo aquellos en los que Claude deba trabajar.
Caducidad: propuesta, 365 días.

La clave (vd_live_…) aparece una sola vez. Justo debajo está la tarjeta «Conectar Claude» con el comando listo, clave incluida.

Tickets, respuestas, finanzas e informes: tú decides

De forma predeterminada, una clave de agente no ve tickets, ni errores, ni tiempos, ni indicadores, no escribe a ningún cliente y no toca facturas, presupuestos, hoja de ruta ni ideas. Cada uno de estos scopes lo activas tú por clave — al crearla o más tarde en «Permisos» en la lista de claves. Para cada uno, el formulario indica qué podrá hacer la clave entonces.

Scope	Qué puede hacer entonces la clave
`tickets:read`	Leer los tickets de sus proyectos, con historial, nombres, direcciones de correo y capturas de pantalla. Lo que lee va al servicio de IA en el que introduces la clave — para ello necesitas un contrato de encargo del tratamiento con su proveedor (art. 28 RGPD).
`tickets:write`	Crear tickets, escribir notas internas y borradores de respuesta. Nada de esto llega al cliente.
`tickets:reply`	Responder a clientes por correo — al momento, sin que una persona lea la respuesta. Igual que «Enviar respuesta»: tu remitente, tu pie, el hilo de correo. Cada respuesta lleva siempre el aviso de que la escribió un asistente de IA. Como máximo 20 respuestas por hora y 3 por ticket y día. Requiere `tickets:read`.
`invoices:write`	Crear borradores de factura en sus proyectos — también a partir de horas pendientes — y cambiar sus partidas. Finalizar, enviar, anular y los pagos siguen siendo cosa tuya; lo impone la base de datos, no solo la interfaz.
`quotes:write`	Crear y cambiar borradores de presupuesto en sus proyectos, mantener sus partidas y volver a eliminarlos. Enviar (y con ello el número), aceptar, rechazar y convertir un presupuesto en factura siguen siendo cosa tuya. No crea presupuestos para un interesado sin ficha de cliente.
`errors:read`	Leer los errores de sus proyectos desde tu rastreador de errores: título, nivel, estado, número de eventos y usuarios afectados, horas, enlace. Sin trazas de pila ni datos de acceso del rastreador.
`errors:write`	Marcar un error abierto como resuelto — primero en el rastreador (con el acceso de tu fuente de errores) y, solo si tiene éxito, en VentionDesk. Si el acceso es de solo lectura, el error sigue abierto y Claude recibe el motivo. Si reaparece, cuenta como regresión («Error de nuevo» en la campana, una tarea nueva según tu umbral). Ocultar y eliminar siguen siendo cosa tuya. Requiere `errors:read`.
`time:read`	Leer las entradas de tiempo de sus proyectos: día, duración, descripción, tarea, facturable y facturado sí/no, nombre de la persona. Sin tarifas por hora ni importes. Los nombres de los miembros de tu equipo van así al servicio de IA.
`stats:read`	Indicadores de sus proyectos para informes: progreso, tareas por estado, tickets abiertos y vencidos, hoja de ruta, monitores, despliegues, pull requests abiertas. Sin ingresos, presupuesto ni costes.
`roadmap:write`	Leer, crear, renombrar, mover, ordenar y marcar como hechas las fases de la hoja de ruta de sus proyectos — la siguiente fase abierta es el hito en el cockpit. Eliminar sigue siendo cosa tuya.
`ideas:write`	Crear ideas nuevas, con uno de sus proyectos o (con «todos los proyectos») sin él. Leer, cambiar y eliminar siguen siendo cosa tuya — también las ideas que creó él mismo.

En el historial de un ticket, cada respuesta del agente está marcada como «enviado por IA» con el nombre de la clave.

2. Conectar Claude Code

Instala Claude Code e inicia sesión; después, en el terminal, en la carpeta de tu proyecto:

claude mcp add --transport http ventiondesk https://api.ventiondesk.com/mcp --header "Authorization: Bearer vd_live_…"

Sustituye vd_live_… por tu clave — o copia el comando directamente de la tarjeta «Conectar Claude». Claude Code habla entonces por HTTP con el servidor MCP de VentionDesk (POST https://api.ventiondesk.com/mcp, sin estado). El servidor acepta claves de agente y el inicio de sesión de una app de IA conectada; rechaza el token de una persona que ha iniciado sesión en el navegador.

Después basta con preguntarle a Claude: «¿Qué tareas están abiertas en VentionDesk?» o «Toma la siguiente tarea del proyecto shop.»

3. Las herramientas

El servidor MCP ofrece 38 herramientas. Cada una llama a la API con tu clave — así que lo que puede hacer una herramienta lo determina la clave. Si le falta el scope, la herramienta responde que falta el permiso.

Herramienta	Qué hace
`ventiondesk_list_projects`	Lista los proyectos que puede ver la clave, opcionalmente por estado.
`ventiondesk_get_project`	Un proyecto por su slug — con repositorio, rama, stack y recuento de tareas.
`ventiondesk_list_tasks`	Lista tareas, filtradas por proyecto, estado y si se pueden tomar ahora mismo.
`ventiondesk_get_task`	Una tarea con descripción, resultados anteriores, contexto del proyecto y, si se piden, imágenes.
`ventiondesk_claim_next_task`	Toma la siguiente tarea abierta según la regla del runner y la muestra completa.
`ventiondesk_claim_task`	Toma una tarea — de forma atómica, dos ejecuciones nunca reciben la misma.
`ventiondesk_report_task_result`	Informa del estado de una tarea y fija así su estado.
`ventiondesk_create_task`	Crea una tarea nueva, para algo que se detecta trabajando (título de 25 caracteres o más).
`ventiondesk_start_run`	Abre una ejecución bajo la que se registran tomas y resultados.
`ventiondesk_finish_run`	Cierra la ejecución con un estado y un resumen de una línea.
`ventiondesk_list_tickets`	Lista los tickets de un proyecto.
`ventiondesk_get_ticket`	Un ticket con su historial.
`ventiondesk_add_ticket_note`	Escribe una nota interna en el historial de un ticket.
`ventiondesk_draft_ticket_reply`	Crea un borrador de respuesta al cliente — no se envía.
`ventiondesk_send_ticket_reply`	Envía al cliente una respuesta por correo — solo con `tickets:reply`.
`ventiondesk_list_invoice_drafts`	Lista los borradores de factura de los proyectos de la clave.
`ventiondesk_get_invoice_draft`	Un borrador de factura con sus partidas.
`ventiondesk_create_invoice_draft`	Crea un borrador de factura en un proyecto.
`ventiondesk_invoice_from_unbilled`	Convierte las horas pendientes de un proyecto en un borrador, una partida por entrada.
`ventiondesk_add_invoice_position`	Añade una partida a un borrador.
`ventiondesk_update_invoice_position`	Cambia una partida de un borrador.
`ventiondesk_delete_invoice_position`	Quita una partida de un borrador.
`ventiondesk_list_quote_drafts`	Lista los borradores de presupuesto de los proyectos de la clave — solo con `quotes:write`.
`ventiondesk_get_quote_draft`	Un borrador de presupuesto con sus partidas.
`ventiondesk_create_quote_draft`	Crea un borrador de presupuesto en un proyecto; el destinatario es el cliente del proyecto.
`ventiondesk_update_quote_draft`	Cambia el título o la validez de un borrador de presupuesto.
`ventiondesk_delete_quote_draft`	Elimina un borrador de presupuesto — todavía no tiene número.
`ventiondesk_add_quote_position`	Añade una partida a un borrador de presupuesto.
`ventiondesk_update_quote_position`	Cambia una partida de un borrador de presupuesto.
`ventiondesk_delete_quote_position`	Quita una partida de un borrador de presupuesto.
`ventiondesk_list_project_errors`	Los errores abiertos de un proyecto — solo con `errors:read`.
`ventiondesk_resolve_error`	Marca un error abierto como resuelto en el rastreador y aquí — solo con `errors:write`.
`ventiondesk_list_time_entries`	Las entradas de tiempo de un proyecto sin tarifas ni importes — solo con `time:read`.
`ventiondesk_get_project_report`	El estado del proyecto para un informe, sin dinero — solo con `stats:read`.
`ventiondesk_list_roadmap`	Las fases de la hoja de ruta de un proyecto — solo con `roadmap:write`.
`ventiondesk_create_roadmap_phase`	Crea una fase de la hoja de ruta.
`ventiondesk_update_roadmap_phase`	Cambia, ordena o marca como hecha una fase.
`ventiondesk_create_idea`	Crea una idea nueva — solo con `ideas:write`.

Sin tickets:reply, Claude prepara las respuestas como borradores y las envía una persona. No hay ninguna herramienta para finalizar, enviar o cobrar una factura, ni para enviar, aceptar o rechazar un presupuesto, para ocultar o eliminar un error, para eliminar una fase ni para leer, cambiar y eliminar ideas.

4. Resultados

Claude informa de cada tarea con uno de seis resultados:

Aviso	Se muestra como	Efecto
`arbeitet`	Sigue trabajando	Avance. La tarea sigue «En proceso».
`kontrolle`	Requiere revisión	Implementado y entregado. Estado «Por revisar» (columna Revisión); exige evidencias.
`frage`	Pregunta para ti	Pregunta. Estado «Pregunta»; la tarea no se vuelve a recoger hasta que alguien responda.
`master`	Pendiente del propietario	Con el propietario, sin cambio de estado; por ejemplo, un paso al que Claude no tiene acceso.
`blockiert`	Bloqueada	No puede continuar. La tarea sigue «En proceso» y la tiene una persona.
`erledigt`	Hecha	Hecho. Estado «Hecha»; exige evidencias.

A «Pregunta», «Requiere revisión», «Pendiente del propietario» y «Bloqueada» respondes en la vista de detalle de la tarea con una aprobación o un rechazo — consulta Tareas y tablero. La tarea vuelve entonces a Claude.

Una ronda como /aufgaben, también sin sistema de archivos (Claude en el navegador o en la app): basta con «Work on the next open VentionDesk task». Claude toma la siguiente tarea —con la misma selección que el runner—, lee la descripción, el historial incluidos los rechazos y el proyecto (repositorio, dirección en vivo, enlace al tablero), obtiene capturas de pantalla solo cuando hacen falta (withAttachments, como máximo tres imágenes de 1 MB cada una, otros archivos como enlace válido durante una hora), comunica el resultado con justificante y cierra la ronda (tomar, comunicar y cerrar la ejecución están en la tabla de arriba). Claude pasa el runId de la toma al aviso y al cierre; una ejecución sin señal de vida queda marcada como agotada tras 30 minutos.

Claude solo toma tareas que no están asignadas a nadie o están asignadas a Claude y que no están aplazadas, en revisión ni terminadas. Una tarea en la que Claude ya ha fallado tantas veces como se permite (de forma predeterminada, tres intentos, ajustable con maxAttempts) VentionDesk ya no la ofrece; cada respuesta de una persona pone el contador a cero.

5. Vincular commits con tareas

Si un mensaje de commit contiene la línea

VentionDesk-Task: <task ID>

VentionDesk vincula el commit con la tarea — siempre que GitHub esté conectado y el repositorio esté indicado en el proyecto. El ID es el UUID de la tarea, tal como lo devuelven la API y las herramientas.

6. Sin MCP: el runner de tareas y la API

Si dejas trabajar a Claude u otra herramienta sin MCP, usa directamente los mismos endpoints:

Iniciar una ejecución (opcional, scope agent:run): POST /v1/agent/runs; durante el trabajo, POST /v1/agent/runs/:id/heartbeat; al final, POST /v1/agent/runs/:id/finish. Una ejecución sin señal de vida se marca como interrumpida al cabo de un tiempo.
Tomar: GET /v1/tasks?projectSlug=<slug>&claimable=true y después POST /v1/tasks/:id/claim.
Informar: POST /v1/tasks/:id/result con state (arbeitet, kontrolle, frage, master, blockiert, erledigt), summaryMd, detailsMd y, con kontrolle y erledigt, pruebas en evidence.
Crear tareas nuevas: POST /v1/tasks.

VentionDesk usa para ello un pequeño runner de tareas hecho de scripts de Node sin dependencias (pull.mjs toma, push.mjs informa con --state, create.mjs crea, finish.mjs cierra la ejecución), controlado mediante las variables de entorno VENTIONDESK_API_KEY y VENTIONDESK_API_URL. No está publicado como paquete; para Claude Code, el camino MCP de arriba es el más sencillo.

Todos los endpoints con parámetros: referencia de la API.