Pular para o conteúdo principal

Conectar um repositório

Este é o fluxo mais comum: você tem uma conta no Almirant (SaaS ou self-hosted) e quer que seu repositório local apareça como um projeto, com agentes de IA acessíveis pelo IDE (Claude Code, Codex, OpenCode, Cursor etc.).

Tempo estimado: 2 minutos.

Requisitos​

  • A CLI instalada (bun add -g almirant@latest ou npm i -g almirant).
  • Uma conta no Almirant. Se ainda não tiver uma, crie-a em almirant.ai ou implante sua própria instância seguindo o guia self-hosted.

Etapa 1 — Autenticar​

Escolha o comando de acordo com o backend em que você se autentica:

# SaaS
almirant login

# Instância self-hosted
almirant login --api-url https://almirant.miempresa.com/api

A CLI abre o navegador para o OAuth e salva a conta em ~/.almirant/config.json com permissões 600.

dica

Você só precisa executar login uma vez por backend. Se trabalha com várias instâncias (por exemplo, SaaS e self-hosted ao mesmo tempo), execute almirant login uma vez para cada uma, atribua rótulos com almirant accounts rename e alterne a ativa com almirant use. Consulte Trabalhar com várias contas.

Etapa 2 — Escolher a conta ativa​

Se tiver mais de uma conta, use rótulos. Daqui a quatro meses você vai lembrar de local-m1pro, não de uma URL longa.

almirant accounts list
almirant accounts rename 1 prod-saas
almirant accounts rename 2 local-m1pro
almirant use local-m1pro
almirant current

Etapa 3 — Vincular o repositório​

Vá até a raiz do repositório que quer conectar e execute:

cd mi-repo
almirant link

A CLI:

  1. Lê suas contas armazenadas e usa a ativa ou permite que você escolha.
  2. Lista os projetos dessa conta e permite escolher um ou criar outro.
  3. Mescla uma entrada almirant em .mcp.json usando o proxy stdio local.
  4. Copia os templates de skills para .claude/skills/ e .agents/skills/.

Se for sua primeira vez e você ainda não tiver executado almirant login, use almirant init em vez de link — init também inicia o fluxo OAuth como parte do mesmo comando.

Etapa 4 — Verificar no IDE​

Abra o repositório no seu agente e peça algo como:

Liste meus work items do Almirant

Se a lista aparecer, está tudo conectado. Se receber Unauthorized, verifique:

  • Se .mcp.json existe na raiz do repositório.
  • Se --account em .mcp.json aponta para uma conta existente (almirant accounts list).
  • Se a API key local ainda está válida (almirant current mostra apenas o prefixo, não o segredo).
  • Se o backend está em execução e acessível, especialmente se for self-hosted.

O que fica no seu repositório​

Depois de link, seu repositório terá:

mi-repo/
├── .mcp.json              ← inicia almirant mcp proxy; não contém tokens
├── .claude/
│   └── skills/            ← templates de skills para Claude Code
└── .agents/
    └── skills/            ← mesmo conteúdo, para agentes que não são Claude

A entrada MCP gerada segue este padrão:

{
  "mcpServers": {
    "almirant": {
      "type": "stdio",
      "command": "almirant",
      "args": ["mcp", "proxy", "--project-id", "<project-id>", "--account", "<account-id>"]
    }
  }
}
informação

A API key fica em ~/.almirant/config.json, não em .mcp.json. O proxy anexa o bearer token em memória quando o agente o inicia.

Codex .codex/config.toml​

Se você usa Codex e o servidor MCP é declarado em .codex/config.toml, use o mesmo proxy:

[mcp_servers.almirant]
command = "almirant"
args = ["mcp", "proxy", "--project-id", "<project-id>", "--account", "<account-id-or-label>"]

Não grave bearer tokens em .codex/config.toml. Se quiser que esse repositório sempre acompanhe a conta ativa, omita --account; para trabalho em equipe ou repositórios antigos, é preferível mantê-lo fixado por ID.

Migrar de configurações antigas​

Se seu .mcp.json contém type: "http", url e Authorization: Bearer ..., execute novamente:

almirant link

Se esse token já esteve no git, faça sua rotação:

almirant config rotate api-key --account <ref>

Gerenciar várias contas e projetos​

Se trabalha com mais de uma conta (caso típico: conta pessoal + empresa, ou SaaS + instância interna), consulte Trabalhar com várias contas.

Para alterar o projeto vinculado de um repositório já inicializado, execute novamente almirant link e escolha o novo projeto — a CLI regrava a entrada almirant de .mcp.json preservando outros servidores.