Documentação

Comece com o Kyroon

Guia self-service para instalar o Kyroon, configurar suas credenciais e conectar o MCP (Model Context Protocol) ao seu agente de IA. Use a busca ou o índice ao lado para navegar entre as seções.

# Instalação

Pré-requisitos

Antes de começar, garanta que os itens abaixo estão disponíveis na sua máquina:

  • Conta Kyroon ativa com um workspace provisionado (criada na compra de um plano ou pelo convite que você recebeu por e-mail).
  • Node.js 22 ou superior — exigido pelo instalador (engines: node >=22).
  • Acesso à internet para baixar os componentes e alcançar a API do Kyroon.
  • Opcional — um cliente compatível com MCP (Claude Code, Cursor ou outro CLI/IDE com Model Context Protocol), se você for usar o Kyroon como ferramenta do seu agente.

A versão do Node.js importa

Com Node.js abaixo de 22 o npm install -g falha com erro de engine, e sem o Node instalado ele falha com command not found. Confirme a versão no Passo 1 antes de prosseguir.

Passo 1 — Verifique o Node.js

Confirme que a versão instalada é 22 ou superior:

bash 
node --version

Se o retorno for menor que v22.0.0 (ou o comando não for encontrado), instale/atualize o Node.js antes de continuar — este é um pré-requisito faltante.

Passo 2 — Instale o Kyroon

A instalação é feita pelo pacote @aikyroon/installer. Um único comando instala Worker, Terminal, App e o Updater nativo.

bash 
npm install -g @aikyroon/installer
kyroon install

kyroon sem argumento equivale a kyroon install.

Ativando na instalação

Se você já tem um código de ativação, informe-o direto no comando para não precisar ativar depois pela interface:

bash 
kyroon install --activation-code ABCD1234

Diagnóstico e remoção

doctor checa o ambiente e os componentes instalados — é o primeiro comando a rodar quando algo não abre ou não conecta. uninstall remove o que foi instalado.

bash 
kyroon doctor
kyroon uninstall

Passo 3 — Registre o MCP do Kyroon no seu agente

Use o comando do seu cliente MCP para adicionar o servidor remoto do Kyroon:

bash 
claude mcp add kyroon \
  --transport http \
  https://api.kyroon.com/mcp \
  --header "Authorization: Bearer $KYROON_API_KEY"

Substitua a URL pelo endpoint do seu ambiente, se aplicável. A variável $KYROON_API_KEY é definida na seção Configuração.

# Configuração

O MCP do Kyroon precisa de credenciais para autenticar e identificar o seu workspace. Defina-as como variáveis de ambiente — nunca as cole diretamente em arquivos versionados.

Variáveis e credenciais

Variável Obrigatória Onde obter / definir
KYROON_API_KEY Sim Painel Kyroon → Configurações → Tokens de API. Gere uma chave e copie o valor (mostrado apenas uma vez).
KYROON_WORKSPACE_ID Sim Painel Kyroon → Workspace → Detalhes. Identifica o workspace alvo das chamadas.
KYROON_API_URL Não Endpoint da API. Padrão: https://api.kyroon.com. Altere apenas para ambientes self-hosted.

Onde definir

Exporte as variáveis no seu shell (Linux/macOS):

bash 
export KYROON_API_KEY="sua-chave-aqui"
export KYROON_WORKSPACE_ID="seu-workspace-id"

No Windows (PowerShell):

powershell 
$env:KYROON_API_KEY = "sua-chave-aqui"
$env:KYROON_WORKSPACE_ID = "seu-workspace-id"

Mantenha sua chave segura

A KYROON_API_KEY concede acesso ao seu workspace. Não a inclua em commits, prints ou tickets de suporte. Se vazar, revogue-a no painel e gere uma nova.

# Uso do MCP

Com o servidor registrado e as credenciais definidas, o seu agente passa a enxergar as ferramentas do Kyroon (criação de subtasks, logs, checklists, status de tarefas, etc.).

1. Registro da tool

Confirme que o servidor kyroon aparece como conectado na lista de servidores MCP do seu cliente:

bash 
claude mcp list

O servidor kyroon deve aparecer com status connected. As ferramentas são expostas com o prefixo mcp__kyroon__*.

2. Autenticação

A autenticação é feita por Bearer token no header Authorization, usando a KYROON_API_KEY definida na Configuração. O workspace alvo é resolvido a partir de KYROON_WORKSPACE_ID. Tokens inválidos ou expirados resultam em 401 Unauthorized.

3. Exemplo de chamada de teste

Para validar a conexão sem efeitos colaterais, faça uma chamada de leitura — por exemplo, listar os agentes do workspace. Diretamente pela API (útil para diagnóstico):

bash 
curl -s https://api.kyroon.com/mcp/health \
  -H "Authorization: Bearer $KYROON_API_KEY" \
  -H "X-Workspace-Id: $KYROON_WORKSPACE_ID"

Ou, dentro do agente, peça que ele liste os agentes do workspace via MCP:

text 
Use a ferramenta mcp__kyroon__list_agents para listar os agentes do meu workspace.

Uma resposta 200 OK (ou a lista de agentes retornada pelo agente) confirma que o registro, a autenticação e o workspace estão corretos.

Troubleshooting

Sintoma Causa provável Como resolver
401 Unauthorized Chave de API ausente, inválida ou revogada. Confira KYROON_API_KEY e gere uma nova chave no painel se necessário.
403 Forbidden Workspace incorreto ou sem permissão. Verifique KYROON_WORKSPACE_ID e os papéis/claims do seu usuário.
Servidor não aparece em mcp list Registro não concluído ou URL incorreta. Refaça o Passo 3 da Instalação e cheque a URL/transport.
command not found Pré-requisito faltante (Node.js / cliente MCP). Revise os Pré-requisitos e instale o que estiver faltando.
EBADENGINE no npm install -g Node.js abaixo de 22 — o instalador exige >=22. Atualize o Node.js e repita o Passo 2.
kyroon não encontrado após instalar Diretório global do npm fora do PATH. Rode npm bin -g e acrescente o caminho ao PATH; depois confirme com kyroon doctor.
Componente instalado não abre ou não conecta Instalação incompleta ou ambiente inconsistente. Rode kyroon doctor — ele aponta o que está faltando antes de qualquer outro diagnóstico.

# FAQ

Preciso pagar para usar o MCP?

O MCP é incluído nos planos do Kyroon. É necessário ter um workspace ativo.

Onde encontro minha chave de API?

No painel Kyroon, em Configurações → Tokens de API. A chave é exibida apenas no momento da criação; guarde-a com segurança. Veja a Configuração.

Posso usar com clientes diferentes do Claude Code?

Sim. Qualquer cliente compatível com Model Context Protocol pode registrar o servidor kyroon. Os comandos exatos variam conforme o cliente; consulte a documentação do seu CLI/IDE.

Recebo 401 mesmo com a chave configurada. O que fazer?

Verifique se a variável de ambiente foi exportada na mesma sessão do terminal e se a chave não foi revogada. Consulte a tabela de Troubleshooting.

Não encontrou sua resposta?

Para temas fora do escopo desta documentação, fale com o suporte em suporte@kyroon.ai.

Editar esta página no GitHub