O MCP (Model Context Protocol) é o caminho recomendado para conectar assistentes de IA ao Backlog, como Claude, Cursor, VS Code e IDEs com suporte a MCP.

MCP do Backlog — conectar agentes de IA

O MCP (Model Context Protocol) é o caminho recomendado para conectar assistentes de IA ao Backlog, como Claude, Cursor, VS Code e IDEs com suporte a MCP.

O que é

O Backlog expõe um servidor MCP com 16 ferramentas para ler e escrever atividades, projetos, comentários, etiquetas e responsáveis. Em vez de você escrever chamadas HTTP, o agente descobre as ferramentas sozinho e as executa.

Endpoint e transporte

Endpoint HTTP de produção: https://mcp.backdocs.online (método POST, também aceita POST /mcp).
Verificação de saúde: GET /health responde {"ok": true}.
O servidor é stateless: cada requisição é independente e carrega sua própria chave.
Há também o modo local via stdio (processo iniciado pelo próprio cliente MCP).

Autenticação

A autenticação usa a mesma chave de API da organização da API REST:

Gere em Configurações → API & MCP (somente administradores).
Envie no header Authorization: Bearer SUA_CHAVE ou x-api-key: SUA_CHAVE.
Sem chave válida o servidor responde 401 e nenhuma ferramenta é executada.
A chave define a organização: o agente só vê dados da sua organização.

Configuração no cliente (HTTP)

{
  "mcpServers": {
    "backlog": {
      "url": "https://mcp.backdocs.online",
      "headers": { "Authorization": "Bearer SUA_CHAVE" }
    }
  }
}

Configuração no cliente (local, stdio)

{
  "mcpServers": {
    "backlog": {
      "command": "npx",
      "args": ["tsx", "CAMINHO_DO_PROJETO/mcp/server.ts"],
      "env": {
        "BACKLOG_BASE_URL": "https://SEU_DOMINIO",
        "BACKLOG_API_KEY": "SUA_CHAVE"
      }
    }
  }
}

No modo stdio, a variável BACKLOG_API_KEY é obrigatória; sem ela o processo encerra com erro.

Ferramentas disponíveis

Ferramenta	O que faz
`list_projects`	Lista os projetos da organização; use o `project_id` para filtrar tarefas
`list_tasks`	Lista atividades com filtros de projeto, status, prioridade, tipo, responsável, prazo e paginação
`get_task`	Detalhe completo: descrição, checklist, responsáveis, etiquetas, comentários e vínculos
`update_task`	Atualiza título, descrição, critérios de aceite, prioridade, prazo, status, checklist ou vínculos
`criar_tarefa`	Cria atividade no projeto informado, com prioridade, prazo, checklist, etiquetas e responsáveis
`add_comment`	Adiciona comentário a uma atividade em nome do agente
`obter_comentarios`	Lista todos os comentários de uma atividade
`buscar_tarefas`	Busca textual por atividades, com filtros
`deletar_tarefa`	Remove uma atividade
`atribuir_tarefa`	Define os responsáveis de uma atividade
`adicionar_item_checklist`	Adiciona itens ao checklist sem remover os existentes
`atualizar_checklist`	Substitui todo o checklist de uma atividade
`criar_projeto`	Cria projeto com board e colunas padrão
`adicionar_etiqueta`	Adiciona uma etiqueta a uma atividade (criada se não existir)
`listar_produtos_servicos`	Lista o catálogo de produtos e serviços, com módulos e funcionalidades
`listar_usuarios`	Lista os membros da organização (id, nome e e-mail)

Exemplos de pedidos ao agente

"Liste as atividades urgentes do projeto Plataforma Backlog e resuma o que falta."
"Crie uma atividade no projeto X: revisar contrato, prioridade alta, prazo 2026-10-01."
"Adicione ao checklist da TEC-123 os itens: revisar copy, validar links."
"Comente na atividade TEC-123 que o deploy foi validado."

Segurança e limites

A chave dá acesso de leitura e escrita aos dados da organização; trate-a como senha.
Prefira include_done: false (padrão) para não poluir o contexto do agente com atividades concluídas.
Use limit para controlar o volume de dados enviados ao modelo e reduzir custo.
Revogar a chave em Configurações → API & MCP interrompe imediatamente qualquer agente conectado.

MCP ou API REST?

MCP: agentes de IA que suportam o protocolo; não exige escrever código de integração.
API REST: integrações próprias, scripts e automações que precisam de controle fino das chamadas.

MCP do Backlog — conectar agentes de IA

On this page