🔧 Instalar e autenticar

Novo aqui? Uma chave de API (API key, sigla de application programming interface — "interface de programação de aplicações", a porta por onde dois programas conversam) é um código único, geralmente uma sequência longa de letras e números, que o serviço usa pra saber quem está fazendo o pedido e cobrar (ou limitar) o uso corretamente. Pense nela como um crachá de visitante: sem ele, a portaria (o servidor do serviço) nem deixa você entrar. Você pega essa chave criando uma conta no site do serviço — no Firecrawl, por exemplo, é um botão "Get API key" no painel, depois de um cadastro rápido, geralmente com um plano gratuito que já dá pra testar.

Cada servidor MCP (o "conector" que dá mãos ao seu agente, explicado nos módulos anteriores) fala com um serviço diferente lá fora, e cada serviço tem sua própria chave. O Firecrawl (que raspa páginas da web) tem uma chave; se depois você ligar um servidor MCP de e-mail ou de planilha, cada um vai pedir a sua. Nenhuma dessas chaves se mistura — cada uma abre só a porta do serviço dela.

Novo aqui? Um arquivo .env é um arquivo de texto simples, dentro da pasta do seu projeto, que guarda segredos — chaves, senhas — fora do código e fora da conversa. Ele nunca deve ser compartilhado nem subido pro GitHub (o site onde o código do seu projeto fica guardado e versionado — a Trilha 0 já tratou como organizar sua pasta; o .env fica junto, mas com um tratamento especial).

O nome do arquivo começa com ponto de propósito: em sistemas do tipo Unix (Mac e Linux), arquivos com ponto na frente ficam "escondidos" por padrão — não aparecem numa lista comum de arquivos, o que reduz a chance de você arrastar ele sem querer pra algum lugar público. Ainda assim, a proteção de verdade não é o nome, é o .gitignore — um segundo arquivo de texto que diz ao git "nunca acompanhe estes arquivos aqui".

Objetivo: guardar a chave fora do alcance do chat e do controle de versão. Como verificar: abra o arquivo .gitignore do projeto e confirme que a linha .env está lá — assim o git nunca vai tentar subir esse arquivo.

Legenda: a chave nasce no site do serviço, entra só no arquivo .env, e é dali que o agente lê quando precisa — o .gitignore e o hábito de nunca digitar a chave no chat fecham as duas portas de vazamento mais comuns.

Nunca cole uma chave de API direto na conversa com o Claude Code. A conversa pode ficar salva em logs, pode ser revisada depois, pode até vazar num print de tela compartilhado sem querer. O arquivo .env existe justamente pra isolar esse segredo — o agente lê dali quando precisa, sem que você precise digitar ele de novo em cada sessão.

Essa regra vale mesmo quando parece mais rápido "só colar aqui pra testar". O ganho de tempo é de segundos; o risco é a chave ficar registrada num lugar que você não controla mais. Se algum dia precisar mostrar seu histórico de conversa pra alguém — suporte técnico, um colega, um print de erro — você quer ter certeza absoluta de que não existe segredo nenhum ali dentro.

Legenda: os quatro passos padrão pra ligar qualquer servidor MCP com segurança — a chave nunca passa pela conversa, só pelo arquivo .env.

Com a chave já no .env, ligar o servidor costuma ser um único comando dentro do Claude Code — o próprio agente pode rodar isso por você se você pedir "instale e configure o servidor MCP do Firecrawl". Ele lê a chave do .env automaticamente, sem você precisar copiar e colar de novo.

Objetivo: deixar o servidor MCP pronto pra uso. Como verificar: rode /mcp no Claude Code e confira se "firecrawl" aparece na lista com status conectado.

Se o comando de instalação der erro, o mais comum é faltar alguma dependência do sistema (o próprio agente costuma indicar o que falta e como instalar) ou o nome da variável no .env não bater com o que o servidor espera — confira se você escreveu exatamente FIRECRAWL_API_KEY, sem espaço antes ou depois do sinal de igual.

Antes de confiar o servidor pra um trabalho grande, teste com um pedido pequeno e fácil de conferir — por exemplo, pedir o título de uma página conhecida. Se o resultado bater com o que você espera, o servidor está redondo.

Objetivo: confirmar que autenticação e conexão funcionam de ponta a ponta. Como verificar: o agente deve devolver o título real da página, sem erro de autenticação nem timeout.

Nem todo erro no teste é sobre a chave. Alguns são do serviço, outros são do site que você está tentando acessar. Reconhecer qual é qual poupa tempo — e evita que você fique mexendo no .env quando o problema está em outro lugar.

Se você desconfiar que uma chave vazou (por exemplo, apareceu sem querer num print ou repositório público), troque ela imediatamente: gere uma nova no painel do serviço, revogue (cancele) a antiga, e atualize só o arquivo .env — nada mais no projeto muda.

Novo aqui? Revogar significa cancelar a validade daquela chave especificamente — o serviço passa a recusar qualquer pedido que chegue com ela, mesmo que a pessoa que a copiou ainda a tenha guardada em algum lugar. É diferente de "apagar sua conta": você continua com acesso normal ao serviço, só que com uma chave nova.

Legenda: o passo 3 (revogar) é o único que realmente fecha o acesso da chave vazada — gerar uma chave nova sem revogar a antiga deixa as duas válidas ao mesmo tempo.