# Conecte seu agente de IA (MCP)

> Dê ao Claude Code, Cursor ou qualquer agente compatível com MCP acesso seguro às suas falhas de CI, além de reexecuções de workflow e jobs avulsos em runners novos por opt-in, para que ele possa fazer triagem, corrigir e verificar a partir do seu editor.

Source: https://latchkey.dev/pt/documentation/connect-your-ai-agent

## Summary

- **Settings, API Keys** cria chaves `lk_live_` para o servidor MCP do Latchkey em `https://latchkey.dev/mcp`.
- Agentes conectados (Claude Code, Cursor, qualquer cliente MCP) podem fazer triagem de falhas, puxar pacotes de falha, verificar o status de execuções, ler o final dos logs, conduzir correções a partir do seu editor e executar jobs avulsos em runners novos.
- A página AI Insight pode entregar uma descoberta direto ao seu agente com **Copy prompt** ou um atalho **Set up MCP**.
- As chaves são somente leitura por padrão, com escopo de workspace, exibidas uma única vez na criação e revogáveis a qualquer momento. Reexecutar workflows, ler o status e os logs de jobs da CLI e executar jobs são, cada um, um opt-in separado e explícito na criação da chave.

O Latchkey traz um **servidor MCP**: seu agente de codificação de IA se conecta a ele com uma chave de API do Latchkey e pode puxar contexto real de falhas de CI (execuções com falha, logs, pacotes de diagnóstico) direto para a sessão do seu editor. Em vez de copiar e colar logs em um chat, seu agente pergunta ao Latchkey diretamente e obtém tudo o que precisa para corrigir a falha.

Esta é a metade de repasse da [autocorreção](/documentation/self-healing): a autocorreção corrige falhas de ambiente durante a execução e nunca toca no seu código-fonte, então quando o problema real é um bug no seu código, o build falha de forma verdadeira, e essa falha chega aqui como um pacote pronto para correção para o seu agente.

Há dois caminhos de entrada: crie uma chave você mesmo em **Settings, API Keys** (a configuração abaixo), ou deixe a página [AI Insight](/documentation/optimization-insights) fazer isso por você. Descobertas que são melhor corrigidas pelo seu próprio agente de codificação oferecem **Copy prompt**, um prompt pronto para colar no seu agente, e um atalho **Set up MCP** que cria uma chave chamada `coding-agent` e mostra o comando exato de conexão. A chave emitida expira em 90 dias e pode executar jobs avulsos em runners cobráveis (o cartão diz isso ao lado do botão), então trate-a como a credencial capaz de gerar gastos que ela é.

## O que um agente conectado pode fazer

O servidor expõe dez capacidades: oito **ferramentas** que seu agente chama para dados e ações, e dois **fluxos de prompt** que orquestram uma tarefa inteira:

- **Listar execuções com falha** Enumere execuções de workflow recentes com falha com seus metadados principais. Jobs da CLI com falha também aparecem.
- **Obter pacote de falha** Puxe o contexto completo de uma falha: logs, diagnóstico e detalhes do workflow.
- **Verificar status da execução** Consulte qualquer execução para ver status, conclusão e a duração de cada job.
- **Ler o final dos logs** Leia o final dos logs (com segredos removidos) de qualquer job concluído, incluindo execuções verdes.
- **Reexecutar um workflow** Dispare uma execução workflow_dispatch para verificar uma correção. Requer uma chave com dispatch habilitado.
- **Executar um job avulso** Execute um comando de shell em um runner novo do Latchkey. Requer uma chave com jobs habilitados e cobra minutos de runner.
- **Verificar status do job** O estado de um job da CLI e, quando ele termina, o código de saída do comando.
- **Ler logs do job** A saída de um job da CLI, para que o agente leia o resultado do comando que executou.
- **Corrigir uma falha de CI** Conduza uma correção guiada de uma falha específica de dentro do seu editor.
- **Triagem de falhas de CI** Examine o que está falhando em seus repositórios monitorados e priorize.

Você nunca os chama pelo nome. Você faz ao seu agente uma pergunta em linguagem simples, e ele decide qual capacidade a responde. Alguns pareamentos ilustrativos:

| Você pergunta ao seu agente | Capacidade que ele aciona |
| --- | --- |
| "O que está falhando em nossos repos agora?" | **Triagem de falhas de CI** |
| "Mostre-me as execuções recentes com falha deste repo" | **Listar execuções com falha** |
| "Puxe tudo que você tem sobre aquela execução com falha" | **Obter pacote de falha** |
| "Corrija o build que está falhando" | **Corrigir uma falha de CI** |
| "Aquela execução passou? Quanto tempo levou cada job?" | **Verificar status da execução** |
| "Mostre-me o final do log do job de deploy" | **Ler o final dos logs** |
| "Enviei a correção, reexecute o CI e acompanhe" | **Reexecutar um workflow** |
| "Execute a suíte de testes em um runner Linux limpo" | **Executar um job avulso** |
| "Aquele job terminou? O que ele imprimiu?" | **Verificar status do job** e **Ler logs do job** |

### Como é uma sessão

Duas sessões ilustrativas. As palavras exatas, e as respostas exatas do agente, vão variar conforme o agente; o formato da troca é o que importa.

## O que há em um pacote de falha

O pacote de falha entrega ao seu agente o que ele de outra forma reconstruiria manualmente:

- A **causa raiz**, em linguagem simples.
- O **código de saída** da etapa que falhou e o arquivo-fonte exato onde o erro surgiu.
- Os **logs completos capturados** da etapa que falhou, incluindo saída que o GitHub esconde em seu visualizador de logs; logs muito grandes mantêm sua parte final e indicam isso. Segredos são removidos antes de os logs saírem do Latchkey.
- O que a **autocorreção já investigou** e por que ela recuou, mais a definição do workflow.

## Configuração

1. **Crie uma chave de API** Abra **Settings, API Keys** (proprietários e administradores gerenciam as chaves). Clique em **Generate key**, dê a ela um nome referente a onde ela vai ficar (por exemplo "Cursor on my laptop"), e escolha uma expiração: **Never** (o padrão), 30 dias, 60 dias, 90 dias ou 1 ano. Marque as capacidades de que a chave precisa (dispatch de workflow, leitura do status e dos logs de jobs da CLI, execução de jobs da CLI); as capacidades são fixadas na criação.
2. **Copie a chave imediatamente** A chave completa (ela começa com `lk_live_`) é exibida **uma única vez**, na criação. Depois disso a interface só mostra um placeholder. Trate-a como uma senha; se você a perder, revogue-a e crie uma nova.
3. **Conecte seu agente** O bloco **Connect your agent** na mesma aba de configurações mostra o comando exato para seu workspace. Para o Claude Code ele fica assim:
4. **Use-a** Pergunte ao seu agente sobre CI que está falhando ("o que está falhando em nossos repos?", "puxe o pacote de falha do último build vermelho e corrija-o"). Qualquer cliente compatível com MCP que suporte transporte HTTP com um cabeçalho bearer funciona da mesma forma.

> **Atalho do Claude Code**
> No Claude Code, o comando integrado `/mcp__latchkey__fix` executa o fluxo de prompt "Corrigir uma falha de CI" em um só passo: ele pega a falha não corrigida mais recente e põe mãos à obra.

## Reexecutar workflows após uma correção (opt-in)

Por padrão, uma chave é somente leitura. Se você quer fechar o ciclo (o agente corrige o código, faz push, reexecuta o CI e acompanha até ficar verde), crie uma chave com **Allow workflow dispatch** marcado. Essa chave carrega adicionalmente o escopo `mcp:dispatch`, e seu agente pode então disparar execuções `workflow_dispatch` nos seus repositórios monitorados, acompanhá-las com a ferramenta de status e ler seus logs quando terminarem. Execuções verdes também são legíveis, então o agente pode confirmar a correção, não apenas observar a falha.

- O dispatch funciona apenas em repositórios que seu workspace monitora, e apenas para workflows que declaram o gatilho `workflow_dispatch`.
- Chaves existentes nunca ganham dispatch retroativamente; crie uma nova chave com a caixa marcada.
- A reexecução roda o que estiver na branch contra a qual você dispara; envie a correção primeiro, depois dispare.

> **Uma chave com dispatch pode disparar qualquer workflow disparável**
> Isso inclui workflows de deploy, se eles forem manualmente disparáveis em um repositório monitorado. Habilite o dispatch apenas em chaves cujo agente você confia com essa superfície, nomeie a chave conforme onde ela vive e revogue-a no momento em que houver dúvida.

## Executar jobs em runners novos (opt-in)

A segunda escrita por opt-in é executar jobs avulsos. Uma chave criada com **Allow running CLI jobs (includes reading)** carrega o escopo `jobs:run` (`jobs:read`, para status e logs, vem junto com ele), e seu agente pode então usar a ferramenta **Executar um job avulso**: um comando de shell em um runner novo e isolado do Latchkey, cobrado como minutos de runner comuns do mesmo pool de minutos gratuitos dos seus workflows. O runner começa limpo, sem conteúdo de repositório; jobs que precisam da sua árvore de trabalho passam pela [CLI do Latchkey](/documentation/latchkey-cli), que a empacota e envia. **Allow reading CLI job status and logs** é a concessão mais restrita (apenas `jobs:read`) para uma chave que deve acompanhar jobs, mas nunca iniciá-los.

- Jobs têm por padrão um timeout de 30 minutos, configurável até 2 horas, e o agente escolhe um tamanho de runner (`small` quando não escolhe).
- Uma chave com jobs habilitados gasta dinheiro: cada job é cobrado pela tarifa padrão por minuto do runner. Nomeie a chave conforme o agente que a detém e dê a ela uma expiração.
- Cancelar um job é uma ação da CLI (`latchkey cancel`), não uma ferramenta MCP.

## Modelo de segurança

- **Somente leitura por padrão.** As chaves podem ler dados de falhas e execuções de CI; mudar qualquer coisa no Latchkey ou no GitHub fica desligado por padrão. As escritas em que uma chave pode optar na criação são o dispatch de workflow (`mcp:dispatch`) e a execução de jobs em runners do Latchkey (`jobs:run`), e nenhuma delas se estende às configurações do Latchkey nem a ações arbitrárias no GitHub.
- **Escopo de workspace.** O workspace é derivado da própria chave, então uma chave só pode ver os dados do seu próprio workspace.
- **Revogável.** Revogue qualquer chave em Settings, API Keys: uma chave com capacidade de escrita (dispatch ou jobs) perde o acesso imediatamente, uma chave somente leitura em cerca de um minuto. Chaves revogadas ficam listadas em uma seção "Revoked (n)" para auditoria.

O que essas três propriedades significam na prática. Somente leitura por padrão limita o raio de impacto de um vazamento: uma chave padrão roubada expõe dados de falha de CI (incluindo trechos de log), razão pela qual você ainda deve protegê-la, mas ela não pode abrir PRs, alterar configurações nem agir no GitHub em seu nome. Uma chave roubada com dispatch habilitado pode, adicionalmente, disparar workflows disparáveis nos seus repositórios monitorados, e uma chave roubada com jobs habilitados pode executar comandos em runners cobráveis no seu workspace, e é exatamente por isso que cada escrita é um opt-in por chave com um aviso na criação, não um padrão. O escopo de workspace significa que não há nada para configurar e nada para errar: a própria chave determina o que ela pode ver, e ela nunca pode ver outro workspace. E como a revogação é rápida e as chaves revogadas continuam listadas para auditoria, a resposta segura a qualquer dúvida é simplesmente revogar e reemitir.

Dois hábitos de baixo esforço que mantêm isso limpo: crie uma chave separada para cada ferramenta ou máquina (o prompt de nomenclatura na criação, como "Cursor on my laptop", existe exatamente para isso), para que revogar uma chave nunca quebre as outras; e escolha a expiração mais curta que se encaixe em como você trabalha, reservando **nunca** para configurações que você acompanha ativamente. O gerenciamento de chaves fica com proprietários e administradores; veja [Equipe e papéis](/documentation/team-and-roles) e [Segurança e permissões](/documentation/security-and-permissions) para o modelo mais amplo.

> **Trate as chaves como senhas**
> Qualquer um que tenha a chave pode ler seus dados de falha de CI (incluindo trechos de log). Guarde-a na configuração do seu agente, não em um repositório, e faça a rotação se ela puder ter vazado.

A Latchkey também publica descritores legíveis por máquina para que um agente descubra a superfície sem precisar ser instruído. A Jobs API REST é servida em `https://api.latchkey.dev` e está totalmente descrita por uma especificação OpenAPI 3.1; o servidor MCP tem seu próprio manifesto listando cada ferramenta e o escopo de que ela precisa.

| Arquivo | O que é |
| --- | --- |
| [/openapi.json](https://latchkey.dev/openapi.json) | Contrato OpenAPI 3.1 da Jobs API: operações, schemas tipados, escopos e formatos de erro. |
| [/.well-known/mcp/manifest.json](https://latchkey.dev/.well-known/mcp/manifest.json) | Descritor do servidor MCP: transporte, autenticação e as oito ferramentas com seus escopos. |
| [/agent.txt](https://latchkey.dev/agent.txt) | Resumo curto em texto simples sobre quando recorrer à Latchkey e como chamá-la. |
| [/llms.txt](https://latchkey.dev/llms.txt) | Índice do site e do conteúdo, com uma seção sobre quando usar. |

Cada página de conteúdo do site também tem uma versão em markdown na mesma URL com `.md`, referenciada no head da página por um link `rel="alternate"`. Ela carrega o mesmo conteúdo sem a marcação da página, o que é muito mais barato para um agente ler.

> **Se seu agente começar a receber 401s**
> Um 401 significa que a chave não autentica mais: ela foi revogada, ou atingiu a expiração que você definiu na criação. A correção é a mesma nos dois casos: crie uma nova chave em Settings, API Keys e atualize o cabeçalho Authorization na configuração do seu agente. Lembre-se de que a chave completa só é exibida uma vez, na criação. Para outros problemas de conexão, comece por [Solução de problemas](/documentation/troubleshooting).

### O que um agente de IA conectado consegue fazer?

Triar falhas, obter pacotes de falha, verificar o status de execuções, acompanhar logs, conduzir correções a partir do seu editor e rodar jobs avulsos em runners novos. Qualquer cliente MCP funciona, incluindo Claude Code e Cursor, contra o servidor MCP do Latchkey em `https://latchkey.dev/mcp`.

### As chaves de API são somente leitura?

Por padrão, sim. As chaves têm escopo de workspace, são exibidas uma única vez na criação e podem ser revogadas a qualquer momento. Reexecutar workflows, ler status e logs de jobs da CLI e executar jobs são opt-ins explícitos e separados, escolhidos na criação da chave, então nada ganha acesso de escrita por acidente.

### Como envio uma descoberta específica para o meu agente?

Pela página AI Insight. O Copy prompt coloca a descoberta e seu contexto na área de transferência em um formato que o agente consegue usar, e um atalho Set up MCP aparece se ainda não houver chave, para você não precisar reconstruir o problema à mão.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt