Suscríbete a eventos a través de MCP

Un agente de IA que esté conectado a Kanera a través de MCP puede solicitar que se le informe cuando cambia el trabajo, en lugar de realizar una encuesta. Kanera implementa la entrega webhook del borrador Eventos MCP extensión: el host del agente registra una devolución de llamada HTTPS, Kanera la verifica y, a partir de ese momento, cada cambio coincidente se publica como una ocurrencia JSON firmada.

Este es el mecanismo detrás de "mira este foro y avísame cuando llegue un comentario" en un cliente como ChatGPT. El anfitrión es propietario de la devolución de llamada; no ejecuta un servidor ni pega una URL en ningún lugar de Kanera.

Para quién es Si usas ChatGPT, lee Mire el trabajo para cambios en ChatGPT y para ahí. El resto de esta página es el contrato a nivel de cable para personas que construyen su propio host MCP o una integración personalizada, y para cualquiera que quiera saber exactamente qué se le puede decir a un agente y qué no. :::

Evento	Se dispara cuando	Campos adicionales en `data`
`card.created`	Se crea una tarjeta en el ámbito monitoreado.	`title`, `listId`, `url`
`card.updated`	Una tarjeta cambia: título, descripción, finalización, estado del archivo y otros campos de la tarjeta.	`title`, `listId`, `url`
`card.moved`	Una tarjeta se mueve dentro o entre listas o tableros.	`listId` (el destino), `fromListId` (la fuente), `prevPosition`, `url`
`card.blocked`	Una tarjeta activa obtiene su primer bloqueador abierto, incluida la reapertura o restauración.	`title`, `listId`, `url`; sin detalles del bloqueador
`card.unblocked`	Una tarjeta activa pierde su último bloqueador abierto al completar, archivar, desvincular o eliminar el tablero o la lista del bloqueador.	`title`, `listId`, `url`; sin detalles del bloqueador
`schedule.conflict_detected`	Una carta abierta gana su primer conflicto de programación: se planea que un bloqueador abierto termine en o después de su inicio.	`blockerCardId`, `days` (días laborables que el dependiente necesitaría mudarse)
`schedule.conflict_resolved`	Una tarjeta abierta pierde su último conflicto de programación.	No hay campos de programación adicionales
`schedule.critical_path_slipped`	El final planificado de una tarjeta de ruta crítica se mueve más tarde y retrasa el final proyectado de su tablero.	`previousProjectedFinish`, `projectedFinish`, `days`, `slipDays`
`comment.created`	Un comentario se publica en una tarjeta.	`commentId`, `text` (hasta 8.000 caracteres), `url`
`priorities.changed`	Tu propio Próximas Es posible que la cola haya cambiado.	Ninguno. Ver Tu próxima cola.
`my_day.ready`	Es una mañana de lunes a viernes en su zona horaria.	`localDate`, `timeZone`. Ver Tu sesión informativa matutina.
`reminder.due`	Uno de los tuyos recordatorios de tarjetas viene debido.	`reminderId`, `cardId`, `remindAt`, `url`. Ver Recordatorios de tu tarjeta.

Cada aparición de tarjeta y comentario lleva workspaceId, boardId, cardId, y un actor (ver Diferenciar tus propias escrituras). Las cargas útiles son resúmenes delimitados: la descripción de una tarjeta, los archivos adjuntos y el hilo de comentarios completo nunca se incluyen. El agente lee el registro actual con cards.get o comments.list cuando necesita más.

Para tarjetas, comentarios y programar eventos, suscripción argumentos limitar lo que se entrega:

Argumento	Requerido	Efecto
`workspaceId`	si	Sólo eventos en este espacio de trabajo.
`boardId`	No	Sólo eventos en este foro. Requerido para invitados a el tablero.
`listId`	No	Solo eventos para tarjetas en esta lista de espacio de trabajo. Para `card.moved`, una tarjeta que entra o sale de la lista coincide y se reordena dentro de ella, no. Omitir `boardId` para ver la lista compartida en cada tablero accesible.
`cardId`	No	Sólo eventos para esta tarjeta. Requiere `boardId`.

El acceso sigue la identidad conectada en cada entrega, no solo en el momento de la suscripción. Un miembro del espacio de trabajo puede observar todo el espacio de trabajo; un invitado de toda la organización debe nombrar un tablero a la que ha sido invitado; un invitado limitado a artículos asignados debe nombrar una tarjeta a la que está asignado actualmente. Si posteriormente la identidad pierde el acceso al alcance, la entrega se detiene y la suscripción caduca. Al perder el acceso a una tarjeta dentro de una suscripción para toda el tablero, solo se omite esa ocurrencia.

Transiciones de dependencia

card.blocked y card.unblocked seguir dependencias de tarjetas, incluidos cambios de personas, integraciones, automatizaciones y tarjetas reflejadas. No requieren una regla de automatización. Agregar un bloqueador adicional o eliminar solo uno de varios bloqueadores no repite la transición. Cada dirección está limitada a una vez por tarjeta y por transacción.

El evento describe la tarjeta dependiente y omite los detalles del bloqueador para proteger los tableros privados. leer cards.get para las relaciones actuales visibles para su conexión. Verifique el estado actual antes de actuar, porque es posible que una automatización ya haya movido o completado la tarjeta.

Programar transiciones

los tres schedule.* Los eventos utilizan el mismo motor de jornada laboral que el Vista de línea de tiempo y work.schedule. Requieren que la línea de tiempo y las dependencias estén habilitadas en la configuración efectiva de la organización/espacio de trabajo, y no requieren una regla de automatización.

schedule.conflict_detected es la transición de ningún conflicto de programación a al menos uno. cardId nombra al dependiente, blockerCardId nombra su peor prerrequisito conflictivo, y days es cuántos días laborables de lunes a viernes necesitaría el dependiente para mudarse correctamente. Agregar otro conflicto no lo repite.
schedule.conflict_resolved significa que a una tarjeta abierta no le quedan conflictos, por ejemplo, después de que cambian las fechas, se completa un bloqueador o se elimina una dependencia. Eliminar sólo uno de varios conflictos no lo activa. Una recurrencia posterior puede desencadenar la detección nuevamente.
schedule.critical_path_slipped requiere que tanto el final planificado de una tarjeta crítica se mueva más tarde como el final proyectado del tablero para moverse más tarde. Un cambio de fecha absorbido por la holgura no califica, ni tampoco la simple adición de nuevos trabajos. days mide hasta dónde se movió la proyección; slipDays mide su retraso con respecto a la última fecha de vencimiento. Una proyección puede moverse más tarde mientras slipDays sigue siendo cero.

La evaluación inicial del cronograma establece una línea de base en lugar de anunciar todos los conflictos existentes. Los eventos informan límites posteriores; utilizar work.schedule para el estado actual al iniciar una vigilancia o recuperarse de entregas perdidas. Léelo nuevamente en un evento antes de sugerir cambios. Estas alertas no reprograman tarjetas.

Para un anfitrión personalizado, suscríbase al nombre de cada evento por separado. Esta solicitud observa los primeros conflictos en un tablero; sustituya el espacio de trabajo real y los UUID del tablero y la devolución de llamada verificada y el secreto de firma del host:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "events/subscribe",
  "params": {
    "name": "schedule.conflict_detected",
    "arguments": { "workspaceId": "…", "boardId": "…" },
    "delivery": {
      "mode": "webhook",
      "url": "https://receiver.example.com/kanera/events",
      "secret": "whsec_…"
    },
    "ttlMs": 86400000
  }
}

Un error en la ruta crítica se ve así (los ID y las fechas son ilustrativos):

{
  "eventId": "evt_…_schedule.critical_path_slipped",
  "name": "schedule.critical_path_slipped",
  "timestamp": "2026-11-02T10:00:00.000Z",
  "data": {
    "workspaceId": "…",
    "boardId": "…",
    "cardId": "…",
    "previousProjectedFinish": "2026-11-06",
    "projectedFinish": "2026-11-09",
    "days": 1,
    "slipDays": 1,
    "actor": { "kind": "user", "userId": "…", "self": false }
  },
  "cursor": null
}

Las fechas son YYYY-MM-DD; las duraciones, la holgura y los recuentos de deslizamientos excluyen los fines de semana. Los eventos de tarjeta y programación pueden describir la misma edición subyacente, pero tienen ID de evento distintos. Reintentos deduplicados por eventId y comprobar actor.self antes de reaccionar a sus propios cambios. Ver ejemplos de planificación.

Tu próxima cola

priorities.changed le dice a un agente que la cola Siguiente del usuario conectado puede haber cambiado, por lo que puede volver a leer la cola en lugar de sondear. Se activa con cada cambio que reordena o cambia el tamaño de la cola:

se agrega, mueve o elimina una entrada, ya sea desde la aplicación web, la API u otro agente;
una tarjeta en cola se completa, archiva, restaura o reasigna, lo que la saca de la cola activa o la devuelve a su lugar.

No requiere argumentos (pasar {}) y nunca tiene como ámbito un espacio de trabajo, porque la cola abarca todos los espacios de trabajo en los que trabaja. La ocurrencia solo incluye quién la cambió:

"data": {
  "targetUserId": "…",
  "actor": { "kind": "user", "userId": "…", "self": false }
}

targetUserId es siempre el usuario conectado. No se incluye nada sobre las tarjetas de la cola. llamar priorities.list para la clasificación actual; aplica la visibilidad normal de su tarjeta.

solo puedes mirar tu propio cola. No hay argumentos a favor de otra persona, y eso incluye a los administradores del espacio de trabajo que pueden leer la cola de un compañero de equipo con priorities.list. Incluso una notificación sin contenido revelaría cuándo y quién completó o reasignó una tarjeta que el observador no puede ver. Un invitado o una clave API de solo lectura también pueden ver su propia cola.

Tu sesión informativa matutina

my_day.ready permite que un agente le informe cada mañana laboral sin su propio programador. Kanera lo envía una vez al día, de lunes a viernes, a las 08:00 en la zona horaria de tu perfil, la misma hora que el correo electrónico de resumen diario. Sigue la configuración del resumen: mientras el correo electrónico del resumen diario esté desactivado, no se envía ningún ping. Se envía independientemente de si se debe o no algo, por lo que el agente aún puede informar un día despejado.

No requiere argumentos (pasar {}) y solo describe tu propio día. La ocurrencia no conlleva trabajo:

"data": {
  "targetUserId": "…",
  "localDate": "2026-10-12",
  "timeZone": "Europe/London",
  "actor": { "kind": "system", "userId": null, "self": false }
}

Luego el agente llama work.my_day con eso timeZone. Una llamada le devuelve sus tarjetas vencidas, las tarjetas vencidas en los próximos siete días, las tarjetas con elementos de la lista de verificación vencidas, las tarjetas asignadas que han estado inactivas durante 14 días o más y la parte superior de su cola Siguiente, todo ello verificado con su acceso actual.

Vuelve también el briefing schedule.conflicts, schedule.critical, y schedule.lateToStart: tus cartas asignadas con conflictos, cartas de ruta crítica sin conflictos y cartas cuyo inicio planificado pasó sin siquiera entrar en progreso. Las verificaciones de inicio tardío requieren un seguimiento del tiempo de progreso y una lista de En progreso, y excluyen las tarjetas que ya están vencidas.

Una suscripción dura hasta 24 horas por actualización, por lo que el cliente debe seguir actualizándola para recibir el ping de la mañana siguiente. ChatGPT hace esto mientras la tarea está activa.

Recordatorios de tu tarjeta

reminder.due permite que un agente actúe cuando uno de sus recordatorios de tarjetas activa, por ejemplo para publicar la tarjeta en un chat o empezar a trabajar en ella. Los recordatorios se configuran desde el botón de alarma de la tarjeta o por un agente con cards.set_reminder. No requiere argumentos (pasar {}) y solo cubre sus propios recordatorios; nadie puede suscribirse al de otra persona.

Kanera verifica los recordatorios vencidos cada 30 segundos y envía una ocurrencia por recordatorio. Reprogramar un recordatorio de que ya se disparó lo arma nuevamente y el próximo disparo es algo nuevo. La ocurrencia nombra la tarjeta pero no lleva nada de su contenido:

"data": {
  "targetUserId": "…",
  "reminderId": "…",
  "cardId": "…",
  "remindAt": "2026-10-16T07:00:00.000Z",
  "url": "https://board.kanera.app/o/…/c/MKT-42",
  "actor": { "kind": "system", "userId": null, "self": false }
}

el agente llama cards.get con el cardId para la tarjeta actual. La entrega comprueba que todavía puedes ver la tarjeta; un recordatorio en una tarjeta que desde entonces ha sido archivada, o a la que ya no puedes acceder, se activa sin una notificación o un evento.

Mire el trabajo para cambios en ChatGPT

Instale y conecte el complemento Kanera usando el Guía de configuración de ChatGPTy luego selecciónelo en una conversación de trabajo que admita tareas basadas en eventos. Un host compatible descubre la capacidad de eventos automáticamente. Para una conexión MCP personalizada, ábrala en Complementos y seleccione Actualizar después de los cambios de servidor. Las actualizaciones de herramientas de complementos publicadas siguen el proceso de revisión de OpenAI.

En una conversación donde esté adjunta la aplicación Kanera, pregunta qué quieres que suceda:

Watch the Product board in Kanera. When a new comment appears on any card, summarise it for me and suggest a reply.

Tell me whenever a card moves into the Done list on the Launch board.

Whenever my Up next queue changes, tell me what is now at the top.

Every weekday morning, brief me on what is overdue, what is due this week, and what is at the top of my Up next queue.

Watch the Launch board for scheduling conflicts and critical-path slips. Read the current schedule when one appears, tell me which cards and dates are affected, and propose a repair. Tell me when conflicts clear. Do not change dates.

ChatGPT crea la suscripción en su propia devolución de llamada alojada, la actualiza mientras la tarea está activa y la finaliza cuando la detiene. Kanera nunca envía su trabajo a ningún lugar que ChatGPT no haya demostrado que controla (consulte Verificación de devolución de llamada).

Se encuentran más ejemplos elaborados, que incluyen responder preguntas en tarjetas, clasificar trabajos nuevos y proteger una sola tarjeta. Ejemplos de cómo utilizar.

Dos cosas que debes saber al escribir la tarea:

Evite los bucles. Cada ocurrencia nombra a su actor y si la conexión de suscripción lo causó. Una tarea que reacciona a los comentarios comentando debe marcar actor.self antes de volver a escribir, o se responderá solo.
Lee antes de escribir. El suceso es un resumen. Solicite a la tarea que lea primero la tarjeta y que utilice las claves de idempotencia de las herramientas para realizar cambios repetibles.

La entrega es el mejor esfuerzo con una ventana de reintento limitada (consulte Entrega y reintentos). Si no se puede acceder a la devolución de llamada de ChatGPT durante más tiempo, la ocurrencia se pasa por alto; la tarea se recupera leyendo el estado actual.

el protocolo

Los eventos solo están disponibles en el punto final HTTP alojado, https://mcp.kanera.app/mcp o el de su propia implementación /mcp, y solo a clientes con el protocolo MCP actual, que es lo que agrega suscripciones a eventos. kanera mcp over stdio no los ofrece: un host stdio local no tiene una devolución de llamada alojada para entregar.

server/discover anuncia la capacidad en ambos capabilities.events (lo que lee ChatGPT hoy) y capabilities.extensions["io.modelcontextprotocol/events"] (donde lo sitúa la propuesta de ampliación). A continuación se presentan tres métodos de solicitud, autenticados exactamente como llamadas a herramientas, con un token de acceso OAuth o una clave API como portador. Los ejemplos siguientes muestran sólo los parámetros del método; la biblioteca cliente agrega los encabezados y metadatos por solicitud del protocolo.

`events/list`

Devuelve el catálogo anterior con un esquema JSON para los argumentos y la carga útil de cada evento. El catálogo es de una sola página; cursor debe estar ausente o vacío.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "events/list",
  "params": {}
}

`events/subscribe`

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "events/subscribe",
  "params": {
    "name": "comment.created",
    "arguments": { "workspaceId": "…", "boardId": "…" },
    "delivery": {
      "mode": "webhook",
      "url": "https://receiver.example.com/kanera/events",
      "secret": "whsec_…"
    },
    "ttlMs": 86400000
  }
}

campo	Reglas
`delivery.mode`	Sólo `webhook` es compatible. Cualquier otro modo regresa `-32014 Unsupported` con `data.feature = "deliveryMode"`.
`delivery.url`	HTTPS, sin credenciales en la URL, sin fragmentos y debe resolverse en una dirección pública. Se rechazan las direcciones de bucle invertido, privadas, de enlace local, de metadatos en la nube y de IPv6 asignadas o de transición.
`delivery.secret`	`whsec_` seguido de 24 a 64 bytes de base64. Kanera lo almacena cifrado y firma cada entrega con él.
`ttlMs`	Vida útil solicitada. El valor predeterminado y el máximo son 24 horas; se respeta un valor positivo más corto, y `null` (sin vencimiento) tiene un límite de 24 horas.
`cursor`, `maxAgeMs`	Aceptado por compatibilidad. Kanera no ofrece repetición: `cursor` siempre se devuelve como `null`, y un cursor de solicitud no nulo se informa como `truncated: true`.

La respuesta:

{
  "id": "sub_…",
  "refreshBefore": "2026-10-07T13:00:00.000Z",
  "cursor": null,
  "truncated": false,
  "deliveryStatus": {
    "active": true,
    "lastDeliveryAt": "2026-10-06T12:58:10.000Z",
    "lastError": null
  }
}

la suscripción id es determinista para la conexión, la URL de devolución de llamada, el nombre del evento y los argumentos (para priorities.changed, my_day.ready, y reminder.due, el usuario conectado), llamando así events/subscribe de nuevo con la misma identidad es un actualizar: se extiende refreshBefore, acepta una nueva secret (tanto la señal secreta antigua como la nueva se entregan durante cinco minutos) y regresa deliveryStatus para una suscripción que todavía estaba activa. deliveryStatus se omite en una primera suscripción y en una renovación después del vencimiento. Actualizar antes refreshBefore; una suscripción vencida que se renueva más tarde comienza desde el momento de la renovación, sin repetir lo que se perdió.

active es siempre true: Kanera nunca suspende una suscripción por fallas en la entrega. En su lugar, limita los reintentos por ocurrencia e informa el estado del punto final a través de lastError (uno de connection_refused, timeout, tls_error, http_4xx, http_5xx, challenge_failed) y failedSince, presente mientras el punto final sigue fallando.

Una conexión puede contener hasta 100 suscripciones activas. El 101 regresa -32013 ResourceExhausted.

`events/unsubscribe`

toma lo mismo name, arguments, y delivery.url, sin ningún secreto. Sólo la conexión que creó una suscripción puede finalizarla; la solicitud de otra credencial no es operativa. Darse de baja es idempotente.

Errores

Kanera utiliza los códigos de error de los borradores de documentos para eventos. Las fallas de suscripción llevan estructuradas data para que un host pueda actuar sobre ellos sin analizar los mensajes.

Código	Nombre	cuando
`-32011`	`NotFound`	`name` no está en el catálogo (`data.kind = "event"`).
`-32012`	`Forbidden`	La identidad no puede ver el alcance solicitado o la credencial no es una clave API o una conexión OAuth.
`-32013`	`ResourceExhausted`	El límite de suscripción (`data.max`) o un límite de tasa.
`-32014`	`Unsupported`	Un modo de entrega distinto al `webhook` (`data.feature`, `data.value`).
`-32015`	`CallbackEndpointError`	La verificación falló. `data.reason` es uno de `connection_refused`, `timeout`, `tls_error`, `http_4xx`, `http_5xx`, o `challenge_failed`. Un destino rechazado se informa como `challenge_failed`, por lo que las respuestas de error no se pueden utilizar para mapear una red privada.
`-32602`	`InvalidParams`	Una solicitud con formato incorrecto, un secreto o URL no válido, un espacio de trabajo, tablero o tarjeta en `arguments` que no existe, o cualquier argumento pasado a `priorities.changed`, `my_day.ready`, o `reminder.due`.

Verificación de devolución de llamada

Antes de almacenar una suscripción, Kanera demuestra que la devolución de llamada es suya. Publica una solicitud de verificación para delivery.url, firmado con el secreto que proporcionaste:

{ "type": "verification", "challenge": "…" }

El punto final debe responder 2xx con un cuerpo JSON que refleja exactamente el desafío:

{ "challenge": "…" }

Cualquier otra cosa falla al suscribirse -32015 y la razón anterior. Nunca se siguen las redirecciones. Una verificación exitosa se almacena en caché durante cinco minutos por conexión y URL de devolución de llamada, por lo que se actualiza o varía. arguments No repite el desafío.

La verificación se ejecuta con la misma política de destino estricta que la entrega: solo direcciones HTTPS públicas, resueltas una vez y fijadas para la conexión, de modo que un cambio de DNS entre la verificación y la solicitud no pueda redirigirla.

Entrega y reintentos

Cada ocurrencia es una POST a la devolución de llamada con Content-Type: application/json:

{
  "eventId": "evt_…",
  "name": "comment.created",
  "timestamp": "2026-10-06T12:58:09.412Z",
  "data": {
    "workspaceId": "…",
    "boardId": "…",
    "cardId": "…",
    "commentId": "…",
    "text": "Can we ship this on Thursday?",
    "url": "https://board.kanera.app/o/3F2A9C1D7B4E6A08/c/PROJ-123",
    "actor": { "kind": "user", "userId": "…", "self": false }
  },
  "cursor": null
}

encabezado	Contenido
`webhook-id`	el `eventId`. Estable entre reintentos; Úselo para hacer que el controlador sea idempotente.
`webhook-timestamp`	Segundos de Unix cuando se firmó este intento. Nuevo en cada reintento.
`webhook-signature`	Uno o más espacios separados `v1,<base64>` firmas (dos durante una rotación secreta).
`X-MCP-Subscription-Id`	la suscripción `id`.

Los bytes del cuerpo son idénticos en cada intento; sólo cambian la marca de tiempo y la firma.

Responder 2xx reconocer. Kanera trata las respuestas de la siguiente manera:

Respuesta	Comportamiento
`2xx`	Entregado. El cuerpo es ignorado.
`410`, `413`y otros `4xx`	Esta ocurrencia se descarta. La suscripción continúa; Los sucesos futuros todavía se entregan.
`408`, `425`, `429`, `5xx`, tiempo de espera, TLS o fallo de conexión	Reintentado con el mismo `eventId`: cinco intentos en total a aproximadamente 0 s, 30 s, 1,5 min, 3,5 min y 7,5 min. Después de eso, la ocurrencia se descarta.

Un cuerpo de respuesta de más de 4 KiB se descarta sin afectar el resultado. Nunca se envía una ocurrencia de más de 256 KiB. Kanera mantiene registros de entrega durante 14 días.

Las entregas de una suscripción activa sobreviven a los reinicios de Kanera. La autorización se vuelve a verificar antes de cada intento, por lo que un agente desconectado, una clave revocada, un miembro eliminado o un invitado que perdió una asignación deja de recibir datos en el siguiente intento, no en la siguiente actualización.

priorities.changed Las ocurrencias se ponen en cola en el momento en que se guarda el cambio de cola, no desde el registro de cambios duradero que utilizan los eventos de tarjeta, porque la cola no está vinculada a un único espacio de trabajo. En el raro caso de que Kanera se reinicie en ese instante, se puede perder una notificación; el siguiente priorities.list La lectura siempre está actualizada.

Verificar la firma

El esquema es el Webhooks estándar diseño. Decodifica el secreto después del whsec_ prefijo de base64, HMAC-SHA256 la cadena {webhook-id}.{webhook-timestamp}.{body}y comparar con cada firma en el encabezado en tiempo constante:

import crypto from "node:crypto";
import express from "express";

const app = express();
const key = Buffer.from(process.env.KANERA_MCP_EVENT_SECRET!.slice("whsec_".length), "base64");

app.post("/kanera/events", express.raw({ type: "application/json" }), (req, res) => {
  const body = req.body.toString("utf8");
  const payload = JSON.parse(body) as { type?: string; challenge?: string };
  const id = req.header("webhook-id") ?? "";
  const timestamp = req.header("webhook-timestamp") ?? "";
  const expected = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest("base64");
  const digest = Buffer.from(expected);
  const valid = (req.header("webhook-signature") ?? "").split(" ").some((entry) => {
    const received = Buffer.from(entry.replace(/^v1,/, ""));
    return received.length === digest.length && crypto.timingSafeEqual(received, digest);
  });
  if (!valid) return res.status(401).send("invalid signature");
  // Verification challenge: echo it back.
  if (payload.type === "verification") return res.json({ challenge: payload.challenge });
  // Occurrence: handle it idempotently by webhook-id.
  res.sendStatus(204);
});

Siempre verifique con el cuerpo crudo. Rechazar entregas cuyo webhook-timestamp Faltan más de unos pocos minutos para la repetición.

Diferenciar tus propias escrituras

Un agente que reacciona a los eventos escribiendo en respuesta verá sus propias escrituras aparecer como eventos. userId por sí solo no puede separarlos: una clave API personal o un agente de OAuth actúa como su usuario, por lo que un comentario publicado por el agente y un comentario publicado por la persona llevan lo mismo userId.

Por lo tanto, cada suceso incluye:

"actor": { "kind": "apiKey", "userId": "…", "self": true }

campo	Significado
`kind`	`user` (la aplicación web), `apiKey`, `agent` (un agente OAuth interactivo), `support`, `automation`, o `system`.
`userId`	El usuario como se realizó el cambio. `null` para automatización y cambios de sistema.
`self`	`true` solo cuando la conexión de suscripción realizó el cambio: la misma concesión del agente OAuth, la misma clave API utilizada directamente o la misma conexión de servicio desatendida.

Los efectos de la automatización se informan como automation incluso cuando la propia escritura del agente los activó, por lo que una regla que agrega una etiqueta después de los comentarios del agente no se lee como escritura del agente.

el title y text Los campos son contenido del usuario. Trátelos como datos, nunca como instrucciones para el agente.

Llamar directamente a la misma API

Los métodos MCP se retransmiten a tres rutas API públicas, que aceptan las mismas credenciales de portador y los mismos cuerpos de solicitud y respuesta. Úselos desde una integración que tenga una clave API y desee suscripciones a eventos sin hablar MCP:

Ruta	método MCP
`GET /api/v1/mcp-events`	`events/list`
`POST /api/v1/mcp-events/subscribe`	`events/subscribe`
`POST /api/v1/mcp-events/unsubscribe`	`events/unsubscribe`

Las fallas se devuelven como documentos públicos de problemas de API con los códigos. MCP_EVENT_NOT_FOUND, MCP_EVENT_UNSUPPORTED, MCP_SUBSCRIPTION_LIMIT, y MCP_CALLBACK_ENDPOINT, que la capa MCP asigna a la tabla de errores anterior.

Para una integración de equipo que debería sobrevivir a cualquier conexión y cubrir todo el catálogo de eventos, utilice Ganchos web en cambio. Las suscripciones a eventos de MCP pertenecen a la credencial que las creó, caducan dentro de las 24 horas a menos que se actualicen y cubren solo los cuatro eventos de tarjetas y comentarios más su propia cola Up next. Los webhooks no entregan los siguientes cambios porque la cola es personal y no datos del espacio de trabajo.

Solución de problemas

problema	Que comprobar
El cliente no ofrece eventos.	Debe conectarse al alojamiento `/mcp` punto final en el protocolo MCP actual. Vuelva a escanear el servidor en el cliente; stdio vía `kanera mcp` Nunca ofrece eventos.
`events/subscribe` regresa `-32015` con `challenge_failed`.	La devolución de llamada no hizo eco del desafío, no respondió a un estado que no fuera 2xx, no fue redirigida ni se encuentra en una dirección privada, de bucle invertido o de metadatos. Kanera informa deliberadamente todo esto de la misma manera.
`-32012 Forbidden` al suscribirse.	La identidad no puede ver el espacio de trabajo, el tablero o la tarjeta. Los invitados a el tablero deben pasar `boardId`; Los invitados que solo tienen artículos asignados deben pasar un área asignada. `cardId`. Las cookies de sesión no pueden suscribirse; utilice una conexión OAuth o una clave API.
Las entregas se detuvieron pero la suscripción aún se actualiza.	comprobar `deliveryStatus.lastError` y `failedSince` en la respuesta de actualización. Si la credencial fue revocada o el usuario perdió el acceso, la suscripción expiró y la actualización no devuelve ningún resultado. `deliveryStatus`.
El agente sigue reaccionando a sus propios comentarios.	comprobar `data.actor.self` antes de escribir.
`-32602` al suscribirse a `priorities.changed`.	pasar vacío `arguments`. un `targetUserId` o se rechaza cualquier otro argumento: sólo se puede observar su propia cola.
Cambios perdidos después de una interrupción.	Los reintentos se detienen después de aproximadamente 7,5 minutos y no hay repetición. Leer el estado actual con `cards.list`, `cards.get`, `comments.list`, o `priorities.list`.

A qué puede suscribirse un agente​

Transiciones de dependencia​

Programar transiciones​

Tu próxima cola​

Tu sesión informativa matutina​

Recordatorios de tu tarjeta​

Mire el trabajo para cambios en ChatGPT​

el protocolo​

events/list​

events/subscribe​

events/unsubscribe​

Errores​

Verificación de devolución de llamada​

Entrega y reintentos​

Verificar la firma​

Diferenciar tus propias escrituras​

Llamar directamente a la misma API​

Solución de problemas​

Páginas relacionadas​

A qué puede suscribirse un agente