Referência de ferramentas MCP

Esta página descreve as ferramentas que o servidor MCP do Priorize.me registra, com os argumentos que cada uma aceita e o formato da resposta. Os exemplos em JSON são verificados contra os schemas do servidor por um teste automatizado; se uma ferramenta mudar, o exemplo desatualizado quebra o build.

Categorias de ferramentas

Ferramentas de leitura (sempre disponíveis)

• list_boards: lista os boards acessíveis
• list_tasks: lista as tarefas de um board, com filtros, paginação e as tags de cada tarefa
• list_board_tags: lista as tags do board, para usar em tagIds
• get_task_activity: lista o histórico de atividade de um board
• list_board_proposals: consulta propostas e seus resultados de revisão humana

Ferramentas de escrita (somente com allowWrites: true)

• create_task: cria uma tarefa, com tags do board se quiser
• update_task: edita título, descrição, prazo e tags do board
• move_task: move a tarefa para outro quadrante ou posição
• complete_task: conclui a tarefa
• discard_task: descarta a tarefa
• reopen_task: reabre uma tarefa concluída ou descartada
• submit_board_proposal: envia uma proposta para revisão, sem alterar tarefas

Com allowWrites desligado, as ferramentas de escrita nem aparecem na lista do cliente.

Propostas para revisão humana

submit_board_proposal exige allowWrites: true, allowlist e papel atual de dono/editor em board ativo. Aceita requestId, boardId, summary opcional (até 2.000 caracteres) e suggestions (até 20). Cada sugestão tem taskId, version inteira positiva, quadrant técnico e reason (até 500 caracteres). Envie pelo menos um resumo ou sugestão. O texto aparece como texto, sem execução.

{
  "name": "submit_board_proposal",
  "arguments": {
    "requestId": "77777777-7777-4777-8777-777777777777",
    "boardId": "11111111-1111-4111-8111-111111111111",
    "summary": "Revise as prioridades antes de aplicar mudanças.",
    "suggestions": []
  }
}

A resposta contém proposal, com id, board_id, summary, summary_closed, suggestions e closed_at. Sugestões têm state: pending, applied, rejected ou obsolete. Donos/editores aplicam ou rejeitam no app; versões inválidas ficam obsoletas. Não há ferramenta MCP para aplicação.

list_board_proposals recebe boardId e cursor opcional. Devolve proposals e, quando há outra página, nextCursor. Este recurso pagina em 50 itens, com cursor associado ao board.

{
  "name": "list_board_proposals",
  "arguments": { "boardId": "11111111-1111-4111-8111-111111111111" }
}

A idempotência de propostas usa o mesmo requestId e conteúdo enquanto a proposta existir. Conteúdo diferente falha. Propostas encerradas expiram após 90 dias; pendentes permanecem até revisão ou exclusão do board. Esse contrato é distinto da janela de sete dias das ferramentas que alteram tarefas.

Identificadores de quadrante

Toda ferramenta usa o identificador técnico do quadrante, nunca o título que aparece no board:

Renomear um quadrante no app muda só a apresentação; os identificadores continuam os mesmos. list_boards devolve os títulos atuais de cada board.

O status de uma tarefa é separado do quadrante: active, completed ou discarded.

Propriedades comuns

• Autorização: toda chamada exige que o board esteja em allowedBoardIds e que a sessão tenha acesso pelo banco (RLS). Um board fora da lista ou sem acesso responde "Board not found or not accessible", igual a um board que não existe.
• Paginação: as listagens devolvem até 25 itens e um nextCursor. Repita a chamada com cursor até nextCursor vir null.
• Idempotência: as escritas exigem requestId (UUID). Repetir o mesmo requestId com os mesmos argumentos, em até 7 dias, devolve o resultado original sem escrever de novo. Depois disso o registro é apagado; gere um requestId novo para cada operação.
• Concorrência otimista: escritas em tarefa existente exigem expectedVersion, a version mais recente que você leu.

Ferramentas de leitura

list_boards

Não recebe argumentos.

{ "name": "list_boards", "arguments": {} }

Resposta:

{
  "boards": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Produto",
      "description": null,
      "archived_at": null,
      "created_at": "2026-09-01T10:30:00Z",
      "quadrants": [
        {
          "id": "urgent-important",
          "title": "Agora",
          "subtitle": "Urgente e importante",
          "color": "teal",
          "customized": true
        }
      ]
    }
  ]
}

quadrants traz os quatro quadrantes do board, personalizados ou não.

list_tasks

{
  "name": "list_tasks",
  "arguments": {
    "boardId": "550e8400-e29b-41d4-a716-446655440000",
    "quadrant": "urgent-important",
    "status": "active"
  }
}

Resposta:

{
  "tasks": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "board_id": "550e8400-e29b-41d4-a716-446655440000",
      "task_number": 12,
      "title": "Revisar proposta",
      "description": null,
      "quadrant": "urgent-important",
      "status": "active",
      "assignee_id": null,
      "due_date": "2026-10-03",
      "tags": [{ "id": "a1d0c6e8-3f4b-4c2d-9e8f-1a2b3c4d5e6f", "name": "Cliente", "color": "teal" }],
      "version": 4,
      "created_at": "2026-09-28T12:00:00Z",
      "updated_at": "2026-09-29T08:15:00Z"
    }
  ],
  "nextCursor": null
}

list_board_tags

{
  "name": "list_board_tags",
  "arguments": {
    "boardId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

A resposta é { "tags": [{ "id", "name", "color" }] }, em ordem alfabética. Os id são os que create_task e update_task aceitam em tagIds. Criar, renomear ou apagar tags continua sendo feito pelo app.

get_task_activity

Lista o histórico de atividade do board inteiro, do mais recente para o mais antigo, com as mesmas regras de visibilidade do app. Para acompanhar uma tarefa, filtre os eventos por entity_id.

{
  "name": "get_task_activity",
  "arguments": { "boardId": "550e8400-e29b-41d4-a716-446655440000" }
}

Resposta:

{
  "events": [
    {
      "id": "9b2f1a4e-0c1d-4e5f-8a9b-1c2d3e4f5a6b",
      "board_id": "550e8400-e29b-41d4-a716-446655440000",
      "actor_id": "3f9a2c1e-1111-4222-8333-444455556666",
      "event_type": "task_moved",
      "entity_type": "task",
      "entity_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "metadata": { "from_quadrant": "backlog", "to_quadrant": "urgent-important" },
      "created_at": "2026-09-29T08:15:00Z"
    }
  ],
  "nextCursor": null,
  "coverageStart": "2026-07-01T00:00:00Z"
}

coverageStart indica desde quando o histórico está disponível (retenção de 90 dias).

Ferramentas de escrita

create_task

{
  "name": "create_task",
  "arguments": {
    "requestId": "0b6a4c55-2f47-4f3a-9d2e-8a1b2c3d4e5f",
    "boardId": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Revisar proposta do Q4",
    "quadrant": "urgent-important",
    "description": "Enviar comentários até sexta",
    "dueDate": "2026-10-03",
    "tagIds": ["a1d0c6e8-3f4b-4c2d-9e8f-1a2b3c4d5e6f"]
  }
}

A resposta é { "task": { ... } }, no mesmo formato de um item de list_tasks. O id da tarefa criada é o próprio requestId, e é isso que torna a repetição idempotente.

Responsáveis, checklist, comentários e anexos não são escritos pelo MCP.

update_task

title é obrigatório. Um campo opcional omitido mantém o valor atual; envie description vazia ("") para apagar a descrição. O prazo não pode ser removido pelo MCP: faça isso pelo app. Sem tagIds, as tags ficam como estão; tagIds: [] remove todas.

{
  "name": "update_task",
  "arguments": {
    "requestId": "5f0c8e1a-7b2d-4c3e-9f4a-1b2c3d4e5f60",
    "boardId": "550e8400-e29b-41d4-a716-446655440000",
    "taskId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "expectedVersion": 4,
    "title": "Revisar proposta do Q4 (urgente)",
    "description": "Enviar comentários até quinta",
    "dueDate": "2026-10-02"
  }
}

Tarefas arquivadas não podem ser editadas: restaure pelo app antes.

move_task

Sem beforeId, a tarefa vai para o fim do quadrante. Só tarefas ativas podem ser movidas.

{
  "name": "move_task",
  "arguments": {
    "requestId": "a3b4c5d6-e7f8-4a9b-8c0d-1e2f3a4b5c6d",
    "boardId": "550e8400-e29b-41d4-a716-446655440000",
    "taskId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "expectedVersion": 5,
    "quadrant": "not-urgent-important"
  }
}

complete_task, discard_task e reopen_task

{
  "name": "complete_task",
  "arguments": {
    "requestId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
    "boardId": "550e8400-e29b-41d4-a716-446655440000",
    "taskId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "expectedVersion": 6
  }
}

{
  "name": "discard_task",
  "arguments": {
    "requestId": "e3f4a5b6-c7d8-4e9f-8a0b-1c2d3e4f5a6b",
    "boardId": "550e8400-e29b-41d4-a716-446655440000",
    "taskId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "expectedVersion": 6
  }
}

{
  "name": "reopen_task",
  "arguments": {
    "requestId": "d2e3f4a5-b6c7-4d8e-9f0a-1b2c3d4e5f6a",
    "boardId": "550e8400-e29b-41d4-a716-446655440000",
    "taskId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "expectedVersion": 7,
    "quadrant": "backlog"
  }
}

Prompts prontos

Além das ferramentas, o servidor oferece dois prompts, que o cliente mostra como atalhos (no Claude Code, por exemplo, aparecem como comandos /). Os dois aceitam boardId opcional; sem ele, o agente pergunta qual board usar.

Os prompts só orientam o agente a usar as ferramentas acima. O raciocínio roda no modelo do seu cliente, não nos servidores do Priorize.me.

Erros

Erros voltam como resultado de ferramenta com isError: true e uma mensagem de texto. Duas classes têm prefixo estável para você decidir o que fazer:

Outras mensagens comuns:

• "Board not found or not accessible": board fora de allowedBoardIds, inexistente ou sem acesso da sessão.
• Erros de validação de argumentos: o cliente MCP mostra o campo e a regra violada.

Boas práticas

• Gere um requestId por operação e reutilize-o só para repetir a mesma operação.
• Leia a tarefa antes de escrever e envie a version que leu.
• Em VERSION_CONFLICT, não repita às cegas: outra pessoa mudou a tarefa.
• Pagine as listagens com cursor em vez de pedir tudo de uma vez.

Próximos passos

• Modelo de segurança
• Configuração do cliente
• Tutoriais de uso
• Solução de problemas