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).
  • Node.js 18+ — necessário para o cliente de linha de comando do seu agente.
  • Um cliente compatível com MCP (Claude Code, Cursor, ou outro CLI/IDE que suporte Model Context Protocol).
  • Acesso à internet para alcançar a API do Kyroon.

Falta algum pré-requisito?

Sem o Node.js 18+ os comandos abaixo falham com command not found. Verifique a versão instalada antes de prosseguir — o bloco a seguir sinaliza automaticamente quando o pré-requisito não é atendido.

Passo 1 — Verifique o Node.js

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

bash 
node --version

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

Passo 2 — 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 2 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.

# FAQ

Preciso pagar para usar o MCP?

O MCP é incluído nos planos do Kyroon. É necessário ter um workspace ativo — consulte os planos & compra.

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.com.

Editar esta página no GitHub