Autenticação MCP

O servidor MCP do Almirant exige uma chave de API válida para todas as operações. A autenticação é feita pelo cabeçalho Authorization com um token Bearer.

Obter uma chave de API

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 - Meu Projeto")
5. Copie a chave de API gerada

Guarde sua chave de API

A chave de API só é exibida uma vez, quando é criada. Copie-a e guarde-a em um local seguro. Se você perdê-la, precisará gerar outra.

Para mais detalhes sobre o gerenciamento de chaves de API, consulte a documentação de API Keys na seção de funcionalidades.

URL do servidor MCP

https://api.almirant.ai/mcp

Para desenvolvimento local:

http://localhost:3001/mcp

Cabeçalho de autenticação

Todas as solicitações devem incluir o cabeçalho:

Authorization: Bearer <tu-api-key>

Configuração no Claude Code

Crie ou edite o arquivo .mcp.json na raiz do projeto:

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

Escopo por projeto

Para limitar as operações a um projeto específico, adicione o parâmetro projectId à URL. Consulte Escopo por projeto para mais detalhes.

Configuração no Cursor

O Cursor oferece suporte nativo ao MCP. Adicione a configuração ao arquivo de configurações MCP do Cursor (.cursor/mcp.json):

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

Configuração global (todos os projetos)

Se preferir que o Almirant esteja disponível em todos os projetos sem criar um .mcp.json em cada um, adicione a configuração em ~/.claude/settings.json:

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

Erros comuns de autenticação

Código	Mensagem	Causa	Solução
401	Unauthorized	Chave de API ausente ou inválida	Verifique se o cabeçalho Authorization inclui Bearer <api-key>
401	API key expired	A chave de API foi revogada	Gere uma nova chave de API em Settings
403	Forbidden	A chave de API não tem permissão para o recurso solicitado	Verifique as permissões da chave de API
500	Error: could not resolve organizationId from API key	A chave de API não está associada a uma organização	Gere uma nova chave de API a partir da organização correta

Verificar a conexão

Depois da configuração, você pode verificar se a conexão funciona usando a ferramenta get_current_user:

{
  "tool": "get_current_user"
}

Essa ferramenta retorna o perfil do usuário autenticado, incluindo id, name, email e organizationId. Se a autenticação falhar, você receberá um erro descritivo.