Conectar ao Claude Code

Esta é a integração central do Almirant. Ao conectar seu IDE ao Almirant via MCP (Model Context Protocol), a IA pode ler suas tarefas, implementar código, mover work items entre colunas e criar pull requests -- tudo sem sair do editor.

O que é MCP e por que conectar

MCP (Model Context Protocol) é um protocolo aberto que permite que ferramentas de IA, como Claude Code ou Cursor, se comuniquem com serviços externos de forma bidirecional. Ao conectar o Almirant via MCP:

• A IA lê seus work items, boards e sprints diretamente
• A IA atualiza o estado das tarefas ao implementar
• A IA cria novos work items quando detecta subtarefas
• A IA acessa o contexto do projeto (tech stack, descrição e objetivos)

Requisitos

Antes de começar, certifique-se de ter:

• Claude Code instalado -- Instruções de instalação
• Um projeto criado no Almirant -- Criar seu primeiro projeto
• Uma API Key do Almirant -- Nós a geraremos no próximo passo

Passo 1: Gerar uma API Key

1. No Almirant, acesse Settings pelo menu lateral
2. Navegue até a seção API Keys
3. Clique em Criar API Key
4. Dê a ela um nome descritivo (por exemplo, "Claude Code - Laptop de trabalho")
5. Copie a API Key gerada

Guarde sua API Key

A API Key é exibida apenas uma vez ao ser criada. Copie-a e guarde-a em um local seguro. Se perdê-la, terá de gerar outra.

Passo 2: Obter o Project ID

Você precisa do ID do projeto ao qual quer conectar a IA. Há duas maneiras de obtê-lo:

Opção A: pela URL

Abra seu projeto no Almirant e copie o UUID exibido na URL do navegador:

https://almirant.ai/projects/a1b2c3d4-e5f6-7890-abcd-ef1234567890
                               └──────────── este é seu projectId ────────────┘

Opção B: pela ferramenta MCP

Se configurar a conexão sem projectId, você pode usar a ferramenta list_projects para ver todos os seus projetos e seus IDs.

Passo 3: Configurar .mcp.json

Crie ou edite o arquivo .mcp.json na raiz do seu repositório:

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=<tu-project-id>",
      "headers": {
        "Authorization": "Bearer <tu-api-key>"
      }
    }
  }
}

Substitua os valores:

Placeholder	Valor
<tu-project-id>	O UUID do projeto obtido no Passo 2
<tu-api-key>	A API Key gerada no Passo 1

Exemplo com valores reais:

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "headers": {
        "Authorization": "Bearer alm_k7x9m2p4q8r1..."
      }
    }
  }
}

Arquivo .mcp.json no repositório

Você pode incluir o .mcp.json no repositório para que toda a equipe compartilhe a mesma configuração. Se fizer isso, adicione a API Key como variável de ambiente em vez de incluí-la diretamente no arquivo.

Passo 4: Verificar a conexão

Abra o Claude Code no terminal e verifique se a conexão funciona:

1. Inicie o Claude Code no diretório do projeto onde criou .mcp.json
2. Peça ao Claude para listar seus projetos:

> Liste meus projetos do Almirant

Se a conexão estiver correta, o Claude responderá com a lista de projetos. Se projectId estiver configurado, ele mostrará os detalhes do projeto específico.

Ferramentas MCP disponíveis após a conexão:

Ferramenta	Descrição
list_projects	Lista os projetos disponíveis
list_boards	Lista os boards do projeto
list_work_items	Lista os work items com filtros
create_work_item	Cria um novo work item
update_work_item	Atualiza um work item existente
list_sprints	Lista os sprints do projeto

Configuração para Cursor

A configuração para Cursor é idêntica. A diferença está na localização do arquivo de configuração:

Cursor usa o mesmo formato .mcp.json. Coloque o arquivo na raiz do projeto ou na configuração global do Cursor, conforme a documentação da sua versão.

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=<tu-project-id>",
      "headers": {
        "Authorization": "Bearer <tu-api-key>"
      }
    }
  }
}

Solução de problemas

A conexão falha ou não responde

1. Verifique a URL -- Certifique-se de que a URL é https://api.almirant.ai/mcp (não https://almirant.ai/mcp)
2. Confira a API Key -- Gere uma nova se não tiver certeza de que a atual está correta
3. Revise o formato JSON -- Um erro de sintaxe em .mcp.json impedirá a conexão

"Unauthorized" ou "Invalid API Key"

• A API Key pode ter sido revogada ou expirado
• Vá para Settings > API Keys no Almirant e gere uma nova
• Atualize o valor no seu .mcp.json

"Project not found"

• Verifique se o projectId na URL está correto
• Confirme que você tem acesso ao projeto com sua conta
• Tente sem projectId e use list_projects para ver os IDs disponíveis

O Claude Code não detecta o servidor MCP

• Certifique-se de que o arquivo .mcp.json está na raiz do diretório em que você executa o Claude Code
• Reinicie o Claude Code depois de criar ou modificar o arquivo
• Verifique se o JSON é válido, sem vírgulas extras e com aspas corretas

---

Próximo passo: Seu primeiro fluxo de IA -- Implemente uma tarefa completa usando IA pelo seu IDE.