Inscreva-se em eventos pelo MCP

Um agente de IA conectado ao Kanera pelo MCP pode pedir para ser informado quando o trabalho mudar, em vez de fazer uma pesquisa. Kanera implementa a entrega do webhook do rascunho Eventos MCP extensão: o host do agente registra um retorno de chamada HTTPS, Kanera o verifica e, a partir de então, cada alteração correspondente é postada nele como uma ocorrência JSON assinada.

Este é o mecanismo por trás de "observe este quadro e me avise quando um comentário chegar" em um cliente como o ChatGPT. O host possui o retorno de chamada; você não executa um servidor nem cola uma URL em qualquer lugar do Kanera.

Para quem se destina Se você usa ChatGPT, leia Observe o trabalho para mudanças no ChatGPT e pare por aí. O restante desta página é o contrato de nível de conexão para pessoas que estão construindo seu próprio host MCP ou uma integração personalizada, e para qualquer pessoa que queira saber exatamente o que um agente pode ou não ser informado. :::

Evento	Incendeia quando	Campos extras em `data`
`card.created`	Um cartão é criado no escopo monitorado.	`title`, `listId`, `url`
`card.updated`	Um cartão muda: título, descrição, conclusão, estado de arquivo e outros campos do cartão.	`title`, `listId`, `url`
`card.moved`	Uma carta se move dentro ou entre listas ou quadros.	`listId` (o destino), `fromListId` (a fonte), `prevPosition`, `url`
`card.blocked`	Uma carta ativa ganha seu primeiro bloqueador aberto, incluindo reabertura ou restauração.	`title`, `listId`, `url`; sem detalhes do bloqueador
`card.unblocked`	Um cartão ativo perde seu último bloqueador aberto ao completar, arquivar, desvincular ou remover o quadro ou lista do bloqueador.	`title`, `listId`, `url`; sem detalhes do bloqueador
`schedule.conflict_detected`	Uma carta aberta ganha seu primeiro conflito de agendamento: um bloqueador aberto está planejado para terminar no seu início ou após ele.	`blockerCardId`, `days` (dias úteis em que o dependente precisaria se mudar)
`schedule.conflict_resolved`	Um cartão aberto perde seu último conflito de agendamento.	Nenhum campo adicional de agendamento
`schedule.critical_path_slipped`	O final planejado de uma carta de caminho crítico se move mais tarde e atrasa o final projetado de seu tabuleiro.	`previousProjectedFinish`, `projectedFinish`, `days`, `slipDays`
`comment.created`	Um comentário é postado em um cartão.	`commentId`, `text` (até 8.000 caracteres), `url`
`priorities.changed`	Seu próprio A seguir a fila pode ter mudado.	Nenhum. Veja Sua próxima fila.
`my_day.ready`	É uma manhã de um dia de semana no seu fuso horário.	`localDate`, `timeZone`. Veja Seu briefing matinal.
`reminder.due`	Um dos seus lembretes de cartão chega devido.	`reminderId`, `cardId`, `remindAt`, `url`. Veja Lembretes do seu cartão.

Cada ocorrência de cartão e comentário carrega workspaceId, boardId, cardId, e um actor (veja Contando o que você escreve separadamente). As cargas úteis são resumos limitados: a descrição de um cartão, os anexos e o tópico de comentários completo nunca são incluídos. O agente lê o registro atual com cards.get ou comments.list quando precisar de mais.

Para cartões, comentários e agendamento de eventos, assinatura argumentos restringir o que é entregue:

Argumento	Obrigatório	Efeito
`workspaceId`	Sim	Somente eventos neste espaço de trabalho.
`boardId`	Não	Apenas eventos neste fórum. Obrigatório para hóspedes do quadro.
`listId`	Não	Apenas eventos para cartões nesta lista de espaço de trabalho. Para `card.moved`, um cartão que entra ou sai da lista corresponde e as reordenações dentro dela não. Omitir `boardId` para assistir a lista compartilhada em todos os quadros acessíveis.
`cardId`	Não	Apenas eventos para este cartão. Requer `boardId`.

O acesso segue a identidade conectada em cada entrega, não apenas no momento da assinatura. Um membro do espaço de trabalho pode observar todo o espaço de trabalho; um convidado de outra organização deve nomear um quadro para o qual foi convidado; um convidado limitado aos itens atribuídos deve nomear um cartão ao qual está atribuído no momento. Se a identidade perder posteriormente o acesso ao escopo, a entrega será interrompida e a assinatura expirará. Perder o acesso a um cartão dentro de uma assinatura de todo o quadro ignora apenas essa ocorrência.

Transições de dependência

card.blocked e card.unblocked siga dependências de cartão, incluindo alterações de pessoas, integrações, automações e cartões espelhados. Eles não exigem uma regra de automação. Adicionar mais um bloqueador ou limpar apenas um dos vários bloqueadores não repete a transição. Cada direção é limitada a uma vez por cartão e por transação.

O evento descreve o cartão dependente e omite detalhes do bloqueador para proteger quadros privados. Leia cards.get para os relacionamentos atuais visíveis para sua conexão. Verifique o estado atual antes de agir, pois uma automação pode já ter movido ou completado o cartão.

Agendar transições

Os três schedule.* eventos usam o mesmo mecanismo de jornada de trabalho que o Visualização da linha do tempo e work.schedule. Eles exigem que o cronograma e as dependências sejam habilitados nas configurações efetivas da organização/espaço de trabalho e não exigem uma regra de automação.

schedule.conflict_detected é a transição de nenhum conflito de agendamento para pelo menos um. cardId nomeia o dependente, blockerCardId nomeia seu pior pré-requisito conflitante, e days é quantos dias úteis de segunda a sexta o dependente precisaria para se mudar para a direita. Adicionar outro conflito não o repete.
schedule.conflict_resolved significa que um cartão aberto não tem mais conflitos, por exemplo, após a mudança de datas, a conclusão de um bloqueador ou a remoção de uma dependência. Limpar apenas um dos vários conflitos não o dispara. Uma recorrência posterior pode acionar a detecção novamente.
schedule.critical_path_slipped requer que o final planejado de uma carta crítica seja movido mais tarde e o final projetado do tabuleiro seja movido mais tarde. Uma mudança de data absorvida pela folga não se qualifica, nem apenas adicionar novo trabalho. days mede até que ponto a projeção se moveu; slipDays mede seu atraso em relação à última data de vencimento. Uma projeção pode se mover mais tarde enquanto slipDays permanece zero.

A avaliação inicial do cronograma estabelece uma linha de base em vez de anunciar todos os conflitos existentes. Os eventos relatam limites subsequentes; usar work.schedule para o estado atual ao iniciar uma observação ou se recuperar de entregas perdidas. Leia novamente em um evento antes de sugerir alterações. Esses alertas não reprogramam cartões.

Para um host personalizado, assine cada nome de evento separadamente. Esta solicitação observa os primeiros conflitos em um quadro; substitua os UUIDs reais do espaço de trabalho e da quadro e o retorno de chamada verificado do host e o segredo de assinatura:

{
  "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
  }
}

Uma ocorrência de deslizamento de caminho crítico é semelhante a esta (IDs e datas são 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
}

As datas são YYYY-MM-DD; durações, folga e contagens de deslizamento excluem fins de semana. Os eventos de cartão e agendamento podem descrever a mesma edição subjacente, mas têm IDs de evento distintos. Desduplicar novas tentativas por eventId e verifique actor.self antes de reagir às suas próprias mudanças. Veja exemplos de planejamento.

Sua próxima fila

priorities.changed informa a um agente que a próxima fila do usuário conectado pode ter sido alterada, para que ele possa reler a fila em vez de pesquisar. Ele é acionado a cada alteração que reordena ou redimensiona a fila:

uma entrada é adicionada, movida ou removida, seja do aplicativo web, da API ou de outro agente;
um cartão na fila é concluído, arquivado, restaurado ou reatribuído, o que o retira da fila ativa ou o coloca de volta.

Não são necessários argumentos (passar {}) e nunca tem como escopo um espaço de trabalho, porque a fila abrange todos os espaços de trabalho em que você trabalha. A ocorrência carrega apenas quem a alterou:

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

targetUserId é sempre o usuário conectado. Nada sobre os cartões da fila está incluído. Ligar priorities.list para a classificação atual; aplica a visibilidade normal do seu cartão.

Você só pode assistir seu próprio fila. Não há argumento a favor de outra pessoa, e isso inclui administradores de espaço de trabalho que podem ler a fila de um colega de equipe com priorities.list. Mesmo uma notificação sem conteúdo revelaria quando e por quem um cartão que o observador não consegue ver foi concluído ou reatribuído. Um convidado ou uma chave de API somente leitura também pode monitorar sua própria fila.

Seu briefing matinal

my_day.ready permite que um agente informe você todas as manhãs de trabalho sem seu próprio agendador. Kanera envia uma vez por dia, de segunda a sexta, às 8h no fuso horário do seu perfil, mesmo horário do e-mail de resumo diário. Ele segue a configuração do resumo: enquanto seu e-mail de resumo diário estiver desativado, nenhum ping será enviado. Ele é enviado independentemente de haver algo devido ou não, para que o agente ainda possa relatar um dia claro.

Não são necessários argumentos (passar {}) e descreve apenas o seu próprio dia. A ocorrência não traz trabalho:

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

O agente então liga work.my_day com isso timeZone. Uma chamada retorna seus cartões vencidos, cartões com vencimento nos próximos sete dias, cartões com itens da lista de verificação vencidos, cartões atribuídos que ficaram inativos por 14 dias ou mais e o topo da sua fila Próximos, todos verificados em relação ao seu acesso atual.

O briefing também retorna schedule.conflicts, schedule.criticale schedule.lateToStart: suas cartas atribuídas com conflitos, cartas de caminho crítico sem conflitos e cartas cujo início planejado passou sem nunca entrar em progresso. As verificações de início tardio exigem monitoramento do tempo em andamento e uma lista Em andamento, e excluem cartões já vencidos.

Uma assinatura dura até 24 horas por atualização, portanto o cliente deve atualizá-la continuamente para receber o ping da manhã seguinte. ChatGPT faz isso enquanto a tarefa está ativa.

Lembretes do seu cartão

reminder.due permite que um agente atue quando um de seus lembretes de cartão disparos, por exemplo, para postar o cartão em um bate-papo ou começar a trabalhar nele. Os lembretes são definidos a partir do botão de alarme do cartão ou por um agente com cards.set_reminder. Não são necessários argumentos (passar {}) e cobre apenas seus próprios lembretes; ninguém pode assinar o de outra pessoa.

Kanera verifica os lembretes vencidos a cada 30 segundos e envia uma ocorrência por lembrete. Reprogramar um lembrete de que já disparou arma-o novamente e o próximo disparo é uma nova ocorrência. A ocorrência nomeia o cartão, mas não carrega nenhum de seu conteúdo:

"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 }
}

O agente liga cards.get com o cardId para o cartão atual. A entrega verifica se você ainda consegue ver o cartão; um lembrete em um cartão que já foi arquivado ou que você não pode mais acessar é acionado sem uma notificação ou evento.

Observe o trabalho para mudanças no ChatGPT

Instale e conecte o plugin Kanera usando o Guia de configuração do ChatGPTe selecione-o em uma conversa de trabalho que ofereça suporte a tarefas orientadas por eventos. Um host compatível descobre a capacidade de eventos automaticamente. Para uma conexão MCP personalizada, abra-a em Plug-ins e selecione Atualizar após alterações no servidor. As atualizações publicadas da ferramenta de plug-in seguem o processo de revisão da OpenAI.

Em uma conversa onde o aplicativo Kanera está anexado, pergunte o que você deseja que aconteça:

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 cria a assinatura em seu próprio retorno de chamada hospedado, atualiza-a enquanto a tarefa está ativa e a encerra quando você interrompe a tarefa. Kanera nunca envia seu trabalho para qualquer lugar que o ChatGPT não tenha provado que controla (veja Verificação de retorno de chamada).

Mais exemplos trabalhados, incluindo responder perguntas em cartões, fazer triagem de novos trabalhos e guardar um único cartão, estão em Exemplos de como usar.

Duas coisas que você deve saber ao escrever a tarefa:

Evite loops. Cada ocorrência nomeia seu ator e se a conexão de assinatura a causou. Uma tarefa que reage aos comentários comentando deve verificar actor.self antes de escrever novamente, ou ele responderá sozinho.
Leia antes de escrever. A ocorrência é um resumo. Peça à tarefa para ler o cartão primeiro e usar as chaves de idempotência das ferramentas para alterações repetíveis.

A entrega é de melhor esforço com uma janela de repetição limitada (consulte Entrega e novas tentativas). Se o retorno de chamada do ChatGPT ficar inacessível por mais tempo, a ocorrência será perdida; a tarefa se recupera lendo o estado atual.

O protocolo

Os eventos estão disponíveis apenas no endpoint HTTP hospedado, https://mcp.kanera.app/mcp ou sua própria implantação /mcpe apenas para clientes no protocolo MCP atual, que é o que adiciona assinaturas de eventos. kanera mcp over stdio não os oferece: um host stdio local não possui retorno de chamada hospedado para entrega.

server/discover anuncia a capacidade em ambos capabilities.events (o que o ChatGPT lê hoje) e capabilities.extensions["io.modelcontextprotocol/events"] (onde a proposta de extensão o coloca). Seguem três métodos de solicitação, autenticados exatamente como chamadas de ferramenta, com um token de acesso OAuth ou uma chave de API como portador. Os exemplos abaixo mostram apenas os parâmetros do método; a biblioteca cliente adiciona os cabeçalhos e metadados por solicitação do protocolo.

`events/list`

Retorna o catálogo acima com um esquema JSON para os argumentos e carga útil de cada evento. O catálogo é uma página única; cursor deve estar ausente ou vazio.

{
  "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	Regras
`delivery.mode`	Somente `webhook` é suportado. Qualquer outro modo retorna `-32014 Unsupported` com `data.feature = "deliveryMode"`.
`delivery.url`	HTTPS, sem credenciais na URL, sem fragmento e deve ser resolvido para um endereço público. Loopback, endereços privados, link-local, metadados em nuvem e endereços IPv6 mapeados em IPv4 ou de transição são recusados.
`delivery.secret`	`whsec_` seguido por 24 a 64 bytes de base64. Kanera o armazena criptografado e assina todas as entregas com ele.
`ttlMs`	Vida útil solicitada. O padrão e o máximo são 24 horas; um valor positivo mais curto é respeitado, e `null` (sem vencimento) é limitado a 24 horas.
`cursor`, `maxAgeMs`	Aceito para compatibilidade. Kanera não oferece replay: `cursor` é sempre retornado como `null`, e um cursor de solicitação não nulo é relatado como `truncated: true`.

A resposta:

{
  "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
  }
}

A assinatura id é determinístico para a conexão, URL de retorno de chamada, nome do evento e argumentos (para priorities.changed, my_day.readye reminder.due, o usuário conectado), então chamando events/subscribe novamente com a mesma identidade é um atualizar: estende refreshBefore, aceita um novo secret (tanto o antigo quanto o novo sinal secreto são entregues por cinco minutos) e retorna deliveryStatus para uma assinatura que ainda estava ativa. deliveryStatus é omitido na primeira assinatura e na renovação após o vencimento. Atualizar antes refreshBefore; uma assinatura expirada e renovada posteriormente começa do zero a partir do momento da renovação, sem repetição do que foi perdido.

active é sempre true: Kanera nunca suspende uma assinatura por falhas na entrega. Em vez disso, ele limita as novas tentativas por ocorrência e relata a integridade do endpoint por meio de lastError (um dos connection_refused, timeout, tls_error, http_4xx, http_5xx, challenge_failed) e failedSince, presente enquanto o endpoint continua falhando.

Uma conexão pode conter até 100 assinaturas ativas. O 101º retorna -32013 ResourceExhausted.

`events/unsubscribe`

Leva o mesmo name, argumentse delivery.url, sem segredo. Somente a conexão que criou uma assinatura pode encerrá-la; a solicitação de outra credencial é autônoma. O cancelamento da assinatura é idempotente.

Erros

Kanera usa os códigos de erro dos rascunhos de documentos para eventos. Falhas de assinatura são estruturadas data para que um host possa agir de acordo com eles sem analisar as mensagens.

Código	Nome	Quando
`-32011`	`NotFound`	`name` não está no catálogo (`data.kind = "event"`).
`-32012`	`Forbidden`	A identidade não pode ver o escopo solicitado ou a credencial não é uma chave de API ou uma conexão OAuth.
`-32013`	`ResourceExhausted`	O limite de assinatura (`data.max`) ou um limite de taxa.
`-32014`	`Unsupported`	Um modo de entrega diferente de `webhook` (`data.feature`, `data.value`).
`-32015`	`CallbackEndpointError`	Falha na verificação. `data.reason` é um dos `connection_refused`, `timeout`, `tls_error`, `http_4xx`, `http_5xx`, ou `challenge_failed`. Um destino recusado é relatado como `challenge_failed`, portanto, as respostas de erro não podem ser usadas para mapear uma rede privada.
`-32602`	`InvalidParams`	Uma solicitação malformada, um segredo ou URL inválido, um espaço de trabalho, quadro ou cartão no `arguments` que não existe, ou qualquer argumento passado para `priorities.changed`, `my_day.ready`, ou `reminder.due`.

Verificação de retorno de chamada

Antes de uma assinatura ser armazenada, Kanera prova que o retorno de chamada é seu. Ele publica uma solicitação de verificação para delivery.url, assinado com o segredo que você forneceu:

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

O endpoint deve responder 2xx com um corpo JSON que reflete exatamente o desafio:

{ "challenge": "…" }

Qualquer outra coisa falha na assinatura com -32015 e o motivo acima. Redirecionamentos nunca são seguidos. Uma verificação bem-sucedida é armazenada em cache por cinco minutos por conexão e URL de retorno, portanto, atualize ou varie arguments não repete o desafio.

A verificação é executada com a mesma política de destino rigorosa da entrega: apenas endereços HTTPS públicos, resolvidos uma vez e fixados para a conexão, de modo que uma alteração de DNS entre a verificação e a solicitação não possa redirecioná-la.

Entrega e novas tentativas

Cada ocorrência é uma POST para o retorno de chamada com 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
}

Cabeçalho	Conteúdo
`webhook-id`	O `eventId`. Estável em todas as tentativas; use-o para tornar o manipulador idempotente.
`webhook-timestamp`	Segundos Unix quando esta tentativa foi assinada. Fresco a cada nova tentativa.
`webhook-signature`	Um ou mais separados por espaço `v1,<base64>` assinaturas (duas durante uma rotação secreta).
`X-MCP-Subscription-Id`	A assinatura `id`.

Os bytes do corpo são idênticos em todas as tentativas; apenas o carimbo de data/hora e a assinatura são alterados.

Responder 2xx reconhecer. Kanera trata as respostas da seguinte forma:

Resposta	Comportamento
`2xx`	Entregue. O corpo é ignorado.
`410`, `413`e outros `4xx`	Esta ocorrência é descartada. A assinatura continua; ocorrências futuras ainda são entregues.
`408`, `425`, `429`, `5xx`, tempo limite, TLS ou falha de conexão	Tentei novamente com o mesmo `eventId`: cinco tentativas no total em aproximadamente 0 s, 30 s, 1,5 min, 3,5 min e 7,5 min. Depois disso, a ocorrência é descartada.

Um corpo de resposta com mais de 4 KiB é descartado sem afetar o resultado. Uma ocorrência acima de 256 KiB nunca é enviada. Kanera mantém registros de entrega por 14 dias.

As entregas de uma assinatura ativa sobrevivem às reinicializações do Kanera. A autorização é verificada novamente antes de cada tentativa, portanto, um agente desconectado, uma chave revogada, um membro removido ou um convidado que perdeu uma atribuição para de receber dados na próxima tentativa, e não na próxima atualização.

priorities.changed as ocorrências são enfileiradas no momento em que a alteração da fila é salva, e não do log de alterações durável usado pelos eventos do cartão, porque a fila não está vinculada a um único espaço de trabalho. No caso raro de o Kanera reiniciar naquele instante, uma notificação pode ser perdida; o próximo priorities.list read é sempre atual.

Verifique a assinatura

O esquema é o Webhooks padrão layout. Decodifique o segredo após o whsec_ prefixo de base64, HMAC-SHA256 a string {webhook-id}.{webhook-timestamp}.{body}e compare com cada assinatura no cabeçalho em tempo 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);
});

Sempre verifique em relação ao corpo bruto. Rejeitar entregas cujo webhook-timestamp faltam mais do que alguns minutos para o replay vinculado.

Contando o que você escreve separadamente

Um agente que reage a eventos escrevendo de volta verá suas próprias escritas surgirem como eventos. userId por si só não pode separá-los: uma chave de API pessoal ou um agente OAuth atua como seu usuário, portanto, um comentário postado pelo agente e um comentário postado pela pessoa carregam o mesmo userId.

Cada ocorrência inclui, portanto:

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

Campo	Significado
`kind`	`user` (o aplicativo da web), `apiKey`, `agent` (um agente OAuth interativo), `support`, `automation`, ou `system`.
`userId`	O usuário com o qual a alteração foi feita. `null` para automação e mudanças no sistema.
`self`	`true` somente quando a própria conexão de assinatura fez a alteração: a mesma concessão do agente OAuth, a mesma chave de API usada diretamente ou a mesma conexão de serviço autônoma.

Os efeitos de automação são relatados como automation mesmo quando a gravação do próprio agente os acionou, portanto, uma regra que adiciona um rótulo após os comentários do agente não é lida como a gravação do agente.

O title e text os campos são conteúdo do usuário. Trate-os como dados, nunca como instruções ao agente.

Chamando a mesma API diretamente

Os métodos MCP retransmitem para três rotas API públicas, que aceitam as mesmas credenciais de portador e os mesmos órgãos de solicitação e resposta. Use-os em uma integração que contém uma chave de API e deseja assinaturas de eventos sem falar MCP:

Rota	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`

As falhas são retornadas como documentos públicos de problemas da API com os códigos MCP_EVENT_NOT_FOUND, MCP_EVENT_UNSUPPORTED, MCP_SUBSCRIPTION_LIMITe MCP_CALLBACK_ENDPOINT, que a camada MCP mapeia na tabela de erros acima.

Para uma integração de equipe que deve sobreviver a qualquer conexão e abranger todo o catálogo de eventos, use Webhooks em vez disso. As assinaturas de eventos MCP pertencem à credencial que as criou, expiram em 24 horas, a menos que sejam atualizadas, e cobrem apenas os quatro eventos de cartão e comentários, além de sua própria fila Próximo. Os webhooks não entregam as próximas alterações porque a fila é pessoal e não dados do espaço de trabalho.

Solução de problemas

Problema	O que verificar
O cliente não oferece eventos.	Ele deve se conectar ao hospedado `/mcp` endpoint no protocolo MCP atual. Verifique novamente o servidor no cliente; estúdio via `kanera mcp` nunca oferece eventos.
`events/subscribe` retorna `-32015` com `challenge_failed`.	O retorno de chamada não ecoou o desafio, respondeu a um status diferente de 2xx, foi redirecionado ou está em um endereço privado, de loopback ou de metadados. Kanera relata deliberadamente tudo isso da mesma maneira.
`-32012 Forbidden` em assinar.	A identidade não pode ver o espaço de trabalho, quadro ou cartão. Os convidados do quadro devem passar `boardId`; convidados apenas com itens atribuídos devem passar por um teste atribuído `cardId`. Os cookies de sessão não podem ser assinados; use uma conexão OAuth ou uma chave de API.
As entregas foram interrompidas, mas a assinatura ainda é atualizada.	Verifique `deliveryStatus.lastError` e `failedSince` na resposta de atualização. Se a credencial foi revogada ou o usuário perdeu o acesso, a assinatura expirou e a atualização não retorna `deliveryStatus`.
O agente continua reagindo aos seus próprios comentários.	Verifique `data.actor.self` antes de escrever.
`-32602` ao assinar `priorities.changed`.	Passe vazio `arguments`. Um `targetUserId` ou qualquer outro argumento é rejeitado: apenas a sua própria fila pode ser monitorada.
Alterações perdidas após uma interrupção.	As novas tentativas param após cerca de 7,5 minutos e não há repetição. Leia o estado atual com `cards.list`, `cards.get`, `comments.list`, ou `priorities.list`.

O que um agente pode assinar​

Transições de dependência​

Agendar transições​

Sua próxima fila​

Seu briefing matinal​

Lembretes do seu cartão​

Observe o trabalho para mudanças no ChatGPT​

O protocolo​

events/list​

events/subscribe​

events/unsubscribe​

Erros​

Verificação de retorno de chamada​

Entrega e novas tentativas​

Verifique a assinatura​

Contando o que você escreve separadamente​

Chamando a mesma API diretamente​

Solução de problemas​

Páginas relacionadas​

O que um agente pode assinar