# 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](https://modelcontextprotocol.io) (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](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

| Peça                   | O que é                                                                                   |
| ---------------------- | ----------------------------------------------------------------------------------------- |
| Servidor MCP           | `https://api.krakendock.com/mcp`, com transporte Streamable HTTP                                       |
| Token de acesso        | credencial que começa com `krk_pat_`, enviada no cabeçalho `Authorization: Bearer …`      |
| Onde criar o token     | [Configurações → Tokens de acesso (MCP)](https://app.krakendock.com/settings/access-tokens)                         |
| O que o assistente faz | usa as [ferramentas](#ferramentas-disponiveis) do servidor, sempre com as suas permissões |

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)](https://app.krakendock.com/settings/access-tokens) 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](#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

| Permissão | O que libera                                                                                             |
| --------- | -------------------------------------------------------------------------------------------------------- |
| Leitura   | sempre incluída: ler projetos, boards, cards, sprints, membros, anexos e a wiki                          |
| Escrita   | criar e editar cards, comentários, sprints, boards, colunas, labels e páginas da wiki; decidir a triagem |
| Exclusão  | excluir cards, comentários, páginas, sprints, colunas, boards e labels, e restaurar cards excluídos      |

- **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)](https://app.krakendock.com/settings/access-tokens) mostra todos os modelos abaixo já com o endereço certo do servidor. Troque `krk_pat_...` pelo seu token.

### Claude Code

No terminal:

```bash
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):

```json
{
  "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:

```json
{
  "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:

```json
{
  "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`](https://www.npmjs.com/package/mcp-remote), que precisa do Node.js instalado. Em **Settings → Developer → Edit Config**, abra o `claude_desktop_config.json` e acrescente:

```json
{
  "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`:

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

| Ferramenta      | Permissão | O que faz                                                                                           |
| --------------- | --------- | --------------------------------------------------------------------------------------------------- |
| `whoami`        | Leitura   | mostra o usuário do token, as permissões e os projetos (se o token for restrito)                    |
| `list_projects` | Leitura   | lista os seus projetos, com a referência `handle/KEY` usada nas outras ferramentas                  |
| `get_project`   | Leitura   | traz o projeto com os boards e as colunas, as labels, os campos customizados e os templates de card |
| `list_members`  | Leitura   | lista as pessoas do projeto; o `user_id` serve para atribuir cards                                  |

### Boards e busca

| Ferramenta     | Permissão | O que faz                                                                                             |
| -------------- | --------- | ----------------------------------------------------------------------------------------------------- |
| `get_board`    | Leitura   | mostra o board com a sprint ativa e as colunas com os cards (sem descrição)                           |
| `get_backlog`  | Leitura   | lista o backlog de um board scrum, com filtros por texto, label, responsável, tipo e prioridade       |
| `search_cards` | Leitura   | busca cards de um projeto por texto e filtros (board, coluna, sprint, responsável, card pai, status…) |
| `search`       | Leitura   | busca em todos os seus projetos: cards, comentários e páginas da wiki                                 |
| `my_cards`     | Leitura   | lista os cards atribuídos a você em todos os projetos, por prazo                                      |

### Cards

| Ferramenta              | Permissão | O que faz                                                                                            |
| ----------------------- | --------- | ---------------------------------------------------------------------------------------------------- |
| `get_card`              | Leitura   | traz o card completo, com comentários, as 20 últimas mudanças, card pai, subtarefas e progresso      |
| `list_attachments`      | Leitura   | lista os arquivos do card e dos comentários                                                          |
| `create_card`           | Escrita   | cria um card, inclusive subtarefas (até 3 níveis), com campos customizados e a partir de um template |
| `update_card`           | Escrita   | edita só os campos enviados; também arquiva, finaliza, reabre e troca o card pai                     |
| `move_card`             | Escrita   | move o card para uma coluna, no topo, no fim ou numa posição; também entre boards do mesmo projeto   |
| `complete_column_cards` | Escrita   | finaliza de uma vez todos os cards de uma coluna de concluídos                                       |
| `delete_card`           | Exclusão  | exclui o card; ele pode ser restaurado por 30 dias                                                   |
| `restore_card`          | Exclusão  | restaura um card excluído na coluna e na posição em que estava                                       |

### Comentários

| Ferramenta       | Permissão | O que faz                                                                                             |
| ---------------- | --------- | ----------------------------------------------------------------------------------------------------- |
| `add_comment`    | Escrita   | comenta em Markdown; num card do Helpdesk, `visibility: requester` responde ao solicitante por e-mail |
| `update_comment` | Escrita   | edita um comentário; só o autor pode                                                                  |
| `delete_comment` | Exclusão  | exclui um comentário de vez                                                                           |

### Sprints

| Ferramenta      | Permissão | O que faz                                                                                  |
| --------------- | --------- | ------------------------------------------------------------------------------------------ |
| `list_sprints`  | Leitura   | lista as sprints do projeto, por board e status                                            |
| `create_sprint` | Escrita   | cria uma sprint planejada num board scrum                                                  |
| `update_sprint` | Escrita   | edita nome, meta e datas de uma sprint planejada ou ativa                                  |
| `start_sprint`  | Escrita   | inicia uma sprint planejada (cada board tem no máximo uma ativa)                           |
| `close_sprint`  | Escrita   | encerra a sprint ativa e manda os cards não concluídos para o backlog ou para outra sprint |
| `delete_sprint` | Exclusão  | exclui uma sprint planejada; os cards dela voltam para o backlog                           |

### Boards, colunas e labels

| Ferramenta      | Permissão | O que faz                                                               |
| --------------- | --------- | ----------------------------------------------------------------------- |
| `create_board`  | Escrita   | cria um board scrum ou kanban, com as colunas padrão                    |
| `update_board`  | Escrita   | renomeia o board, troca a metodologia ou a posição                      |
| `delete_board`  | Exclusão  | exclui um board sem cards e sem sprint ativa; nunca o último do projeto |
| `create_column` | Escrita   | cria uma coluna no fim do board, com limite de WIP opcional             |
| `update_column` | Escrita   | renomeia, marca como concluída, muda a posição ou o limite de WIP       |
| `delete_column` | Exclusão  | exclui uma coluna vazia; nunca a última do board                        |
| `create_label`  | Escrita   | cria uma label com cor `#RRGGBB`                                        |
| `update_label`  | Escrita   | renomeia a label ou troca a cor                                         |
| `delete_label`  | Exclusão  | exclui uma label                                                        |

### Wiki

| Ferramenta           | Permissão | O que faz                                                                    |
| -------------------- | --------- | ---------------------------------------------------------------------------- |
| `get_wiki_tree`      | Leitura   | lista as páginas do projeto (id, página pai e título)                        |
| `get_wiki_page`      | Leitura   | traz a página em Markdown; com `version`, lê uma versão antiga               |
| `list_wiki_versions` | Leitura   | lista as versões salvas de uma página                                        |
| `create_wiki_page`   | Escrita   | cria uma página, opcionalmente dentro de outra                               |
| `update_wiki_page`   | Escrita   | substitui o conteúdo da página; recusa a edição se outra pessoa salvou antes |
| `delete_wiki_page`   | Exclusão  | exclui uma página sem páginas filhas                                         |

### Triagem

| Ferramenta    | Permissão | O que faz                                                                                        |
| ------------- | --------- | ------------------------------------------------------------------------------------------------ |
| `list_triage` | Leitura   | lista as propostas de quem não é membro que esperam decisão, das mais antigas para as mais novas |
| `triage_card` | Escrita   | aceita a proposta num board, recusa com um motivo ou pede mais informações ao autor              |

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

| Limite                        | Valor                                                   |
| ----------------------------- | ------------------------------------------------------- |
| Requisições ao servidor MCP   | 120 por minuto por pessoa, somando todos os tokens dela |
| Tokens ativos por pessoa      | 20                                                      |
| Projetos num token restrito   | 50                                                      |
| Nome do token                 | até 100 caracteres                                      |
| Tentativas com token inválido | limitadas por IP; só as tentativas erradas contam       |

- 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](#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)](https://app.krakendock.com/settings/access-tokens) 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](https://app.krakendock.com/docs/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](https://app.krakendock.com/docs/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

| Sintoma                                                               | Causa provável                                                                                             |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `401 UNAUTHENTICATED`                                                 | falta o cabeçalho `Authorization: Bearer krk_pat_...`                                                      |
| `401 INVALID_TOKEN`                                                   | token errado, revogado ou vencido. Uma troca de senha revoga todos os tokens                               |
| `403 TERMS_NOT_ACCEPTED`                                              | aceite os Termos de Uso atuais entrando no KrakenDock pelo navegador                                       |
| `429 RATE_LIMITED`                                                    | passou de 120 requisições por minuto, ou de tentativas com token inválido. Espere o tempo do `Retry-After` |
| O assistente não oferece criar nem excluir                            | o token não tem **Escrita** ou **Exclusão**. Crie outro token com a permissão                              |
| `PROJECT_NOT_FOUND`                                                   | o projeto não está no token, você não é membro ou a chave está errada                                      |
| `AMBIGUOUS_REFERENCE`                                                 | dois projetos seus têm a mesma chave. Use `handle/KEY`                                                     |
| `ACCESS_TOKEN_LIMIT_REACHED` ao criar um token                        | você já tem 20 tokens ativos. Revogue um                                                                   |
| `Accept must contain both 'application/json' and 'text/event-stream'` | num teste com `curl`, faltou o cabeçalho `Accept` do exemplo                                               |

## Veja também

- [Primeiros passos](https://app.krakendock.com/docs/getting-started)
- [Boards, cards e sprints](https://app.krakendock.com/docs/boards)
- [IA: reuniões e textos em cards](https://app.krakendock.com/docs/ai)
- [Webhooks](https://app.krakendock.com/docs/webhooks)
- [Open source e contribuições](https://app.krakendock.com/docs/open-source), para a triagem de propostas
- [Helpdesk](https://app.krakendock.com/docs/helpdesk)