Servidor MCP e tokens de acesso

Conecte assistentes de IA como Claude Code, Cursor, VS Code e Claude Desktop ao KrakenDock pelo Model Context Protocol (MCP). O assistente lê seus projetos e, se você deixar, cria e move cards, comenta, cuida das sprints e edita a wiki por você.

O acesso usa um token de acesso pessoal, criado por você e revogável a qualquer momento. Este guia é para quem usa o KrakenDock com um assistente de IA no dia a dia.

Versão em Markdown puro deste guia: https://app.krakendock.com/docs/mcp.md?lang=pt-BR. Use-a para colar num assistente de IA ou na documentação interna do seu time.

Visão geral

O assistente age em seu nome. O token nunca dá mais acesso do que você já tem: ele só pode reduzir esse acesso, com as permissões e os projetos que você escolher.

Conectar em 5 minutos

1. Abra Configurações → Tokens de acesso (MCP) e clique em Novo token.
2. Dê um Nome que lembre onde o token vai ser usado (por exemplo, "Claude Code no notebook").
3. Escolha as Permissões, os Projetos e a Expiração. Veja Tokens de acesso.
4. Clique em Criar token e copie o token na hora. Ele aparece uma única vez.
5. Na mesma janela, em Conectar um assistente, escolha a aba do seu assistente e copie a configuração, que já vem com o token e o endereço do servidor.
6. Peça ao assistente: "Quem sou eu no KrakenDock?". Ele deve responder com o seu usuário (ferramenta whoami).

Depois de clicar em Já copiei o token, o token some da tela. Os modelos de configuração continuam em Como conectar, com o marcador <SEU_TOKEN> no lugar do token.

Tokens de acesso

Permissões do token

• Escrita e Exclusão são independentes. Um token com Exclusão e sem Escrita só lê e exclui.
• As ferramentas fora das permissões do token nem aparecem para o assistente.
• Para um assistente que só consulta, crie o token só com Leitura.

Projetos do token

• Todos os projetos: o token alcança todos os projetos de que você é membro, inclusive os que entrarem depois.
• Projetos específicos: escolha até 50 projetos. Qualquer outro projeto responde como se não existisse (PROJECT_NOT_FOUND).
• Se todos os projetos escolhidos forem excluídos, o token não alcança mais nada. A lista mostra Projeto indisponível no lugar deles.

Expiração do token

• Escolha 30 dias, 90 dias (o padrão), 1 ano ou Sem expiração.
• Um token vencido continua na lista com o selo Expirado até você revogá-lo, mas não funciona mais.
• Não dá para renovar um token: crie outro e troque na configuração do assistente.

Revogar um token

Na lista Seus tokens, clique em Revogar na linha do token e confirme. Os assistentes que usam esse token perdem o acesso na hora. A ação não pode ser desfeita.

A lista mostra, para cada token, o começo dele (por exemplo, krk_pat_Ab3d…), as permissões, os projetos, a data de criação, o Último uso e quando expira. Use o Último uso para achar tokens esquecidos.

Quando o token para de funcionar

• Quando você o revoga ou ele expira.
• Quando você troca ou redefine a senha: todos os seus tokens são revogados, porque quem sabia a senha antiga pode tê-los criado.
• Quando a conta é excluída.
• Enquanto você não aceitar a versão atual dos Termos de Uso: o servidor responde 403 TERMS_NOT_ACCEPTED. Entre no KrakenDock pelo navegador e aceite os termos.

Cada pessoa pode ter até 20 tokens ativos. Os tokens vencidos e os revogados não contam.

Configurar o assistente

A tela Tokens de acesso (MCP) mostra todos os modelos abaixo já com o endereço certo do servidor. Troque krk_pat_... pelo seu token.

Claude Code

No terminal:

claude mcp add --transport http kraken https://api.krakendock.com/mcp \
  --header "Authorization: Bearer krk_pat_..."

• Por padrão, o servidor vale só para a pasta atual. Para usar em todos os projetos, acrescente --scope user.
• Com --scope project, a configuração vai para o arquivo .mcp.json do repositório. Nesse caso, não grave o token no arquivo: use "Authorization": "Bearer ${KRAKEN_TOKEN}" e defina a variável de ambiente KRAKEN_TOKEN na sua máquina.
• Confira com claude mcp list ou, dentro do Claude Code, com /mcp.

Cursor

Arquivo ~/.cursor/mcp.json (para todos os projetos) ou .cursor/mcp.json (só para um projeto):

{
  "mcpServers": {
    "kraken": {
      "url": "https://api.krakendock.com/mcp",
      "headers": { "Authorization": "Bearer krk_pat_..." }
    }
  }
}

O Cursor também aceita "Bearer ${env:KRAKEN_TOKEN}", lendo o token de uma variável de ambiente. Reinicie o Cursor depois de mudar o arquivo.

VS Code

Arquivo .vscode/mcp.json do projeto:

{
  "servers": {
    "kraken": {
      "type": "http",
      "url": "https://api.krakendock.com/mcp",
      "headers": { "Authorization": "Bearer krk_pat_..." }
    }
  }
}

Se a pasta .vscode vai para o Git, peça o token ao abrir, em vez de gravá-lo no arquivo:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "kraken-token",
      "description": "Token do KrakenDock",
      "password": true
    }
  ],
  "servers": {
    "kraken": {
      "type": "http",
      "url": "https://api.krakendock.com/mcp",
      "headers": { "Authorization": "Bearer ${input:kraken-token}" }
    }
  }
}

Claude Desktop

O Claude Desktop conversa com o servidor por meio do mcp-remote, que precisa do Node.js instalado. Em Settings → Developer → Edit Config, abra o claude_desktop_config.json e acrescente:

{
  "mcpServers": {
    "kraken": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.krakendock.com/mcp",
        "--header",
        "Authorization: Bearer krk_pat_..."
      ]
    }
  }
}

Reinicie o Claude Desktop. No Windows, o espaço em Authorization: Bearer … pode quebrar o argumento. Nesse caso, passe "Authorization:${AUTH_HEADER}" (sem espaço) no lugar do cabeçalho e defina "env": { "AUTH_HEADER": "Bearer krk_pat_…" } no mesmo bloco, como indica o README do mcp-remote.

Os conectores remotos do claude.ai ("Adicionar conector personalizado") ainda não funcionam com o KrakenDock: eles não permitem enviar um cabeçalho Authorization próprio (só OAuth), e o servidor aceita só o token.

Testar a conexão

Peça ao assistente para usar a ferramenta whoami. Ela mostra o seu usuário, as permissões do token e, se ele for restrito, os projetos.

Para testar sem assistente, chame a ferramenta direto com curl:

curl https://api.krakendock.com/mcp \
  -H "Authorization: Bearer krk_pat_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}'

Ferramentas disponíveis

São 43 ferramentas, agrupadas abaixo por assunto. A coluna Permissão diz qual permissão do token faz a ferramenta aparecer.

Conta e projetos

Boards e busca

Cards

Comentários

Sprints

Boards, colunas e labels

Wiki

Triagem

As ferramentas de exclusão pedem ao assistente que confirme com você antes. Cada ferramenta também avisa o cliente se só lê, se escreve ou se é destrutiva, e muitos clientes usam isso para decidir quando pedir confirmação.

Exemplos de pedidos

• "Quais cards estão atribuídos a mim, por prazo?"
• "Mostre o board do projeto acme/APP e me diga o que está parado em revisão."
• "Crie uma história 'Checkout com Pix' no APP e quebre em subtarefas de API, web e testes."
• "Mova o APP-42 para Em andamento e atribua a mim."
• "Leia o APP-57 e os comentários e resuma o que falta decidir."
• "Feche a sprint atual do APP e mande o que não terminou para a próxima sprint."
• "Atualize a página 'Arquitetura' da wiki com a decisão que acabamos de tomar."
• "Liste as propostas na triagem do APP e recuse as duplicadas."

O assistente se vira com nomes e chaves. Para referências exatas:

• Projeto: UUID, handle/KEY (seu usuário ou o slug da organização, mais a chave, como acme/APP) ou só KEY, se não houver outro projeto seu com a mesma chave. Uma chave repetida responde AMBIGUOUS_REFERENCE.
• Card: UUID, handle/KEY-N ou KEY-N, com a mesma regra.
• Boards, colunas, sprints, labels, comentários e páginas: UUID, que as ferramentas de listagem devolvem.
• Responsável: me vale como você.

As respostas trazem a url de cada item no KrakenDock, para o assistente mandar o link.

Permissões

• Tudo roda com as suas permissões em cada projeto. Se o seu papel não deixa editar cards num projeto, o assistente também não edita, mesmo com um token de Escrita.
• O token só alcança projetos de que você é membro: direto, por um time ou pela organização. Projetos públicos de outras pessoas ficam de fora, tanto para ler quanto para contribuir.
• Se a organização exige verificação em duas etapas e você ainda não a ativou, os projetos dela ficam fora do alcance do token.
• A triagem pede a permissão Gerenciar projeto ou a permissão de triagem do projeto.
• O board Helpdesk segue a mesma regra do web: só membros do projeto o veem.
• O que o assistente faz gera as mesmas notificações e atualizações em tempo real que uma ação sua no navegador.

Limites

• Passou do limite, o servidor responde 429 RATE_LIMITED com o cabeçalho Retry-After.
• O servidor MCP está disponível em todos os planos, e nenhuma ferramenta consome créditos de IA.

Segurança

• Trate o token como uma senha. Quem tem o token age como você, dentro das permissões e dos projetos dele.
• Nunca grave o token num repositório. Use variáveis de ambiente ou o pedido de senha do cliente (veja os exemplos em Configurar o assistente).
• Crie um token por máquina ou por assistente. Assim você revoga um sem derrubar os outros.
• Dê só o necessário: Leitura para consultas, Projetos específicos quando o assistente trabalha num projeto só, e Exclusão só se precisar mesmo.
• Prefira tokens com expiração.
• Vazou? Revogue o token na hora em Tokens de acesso (MCP) e crie outro. Se não sabe qual vazou, troque a senha: isso revoga todos.
• O KrakenDock guarda só um resumo criptográfico (hash) do token. Por isso ele não pode ser mostrado de novo.

Perguntas frequentes

Posso usar o token na API REST?

Não. O token de acesso pessoal vale só no servidor MCP (/mcp). A API REST do KrakenDock usa a sessão do navegador e não aceita esse token. Para integrar outros sistemas, use os webhooks.

O assistente consegue baixar anexos?

Não. list_attachments traz o nome, o tipo, o tamanho e um link de cada arquivo. O link abre no navegador para quem está logado no KrakenDock, mas o assistente não baixa o arquivo com o token.

Por que o assistente não encontra um projeto?

Confira se você é membro do projeto e se ele está entre os projetos do token. Projetos públicos de que você não é membro ficam de fora. Peça um whoami para ver os projetos do token.

Como sei o que foi feito pelo assistente?

Os cards criados pelo assistente recebem a origem "Via IA (MCP)", e o histórico do card marca as mudanças com "via MCP". A autoria continua sendo sua.

O assistente pode responder chamados do Helpdesk?

Sim, com um token com Escrita. get_card traz a conversa com o solicitante, e add_comment com visibility: requester responde por e-mail. Sem esse parâmetro, o comentário é uma nota interna. Veja o guia do Helpdesk.

O que acontece se duas pessoas editarem a mesma página da wiki?

update_wiki_page exige a versão atual da página. Se alguém salvou antes, a edição é recusada, e o assistente precisa ler a página de novo e juntar as mudanças.

Solução de problemas

Veja também

• Primeiros passos
• Boards, cards e sprints
• IA: reuniões e textos em cards
• Webhooks
• Open source e contribuições, para a triagem de propostas
• Helpdesk