Como pedir ao Claude Code para integrar uma API externa que você nunca usou?

Você pede a integração e em poucos segundos o cliente da API tá pronto: função de autenticação, tratamento de erro, tipagem, tudo bonitinho

O problema é que "bonitinho" não quer dizer "existe"

O agente pode ter chutado o nome do campo, o formato do token ou uma rota /v2/ que nunca foi publicada, e você só descobre isso quando roda contra o servidor de verdade

E olha, isso não é defeito do Claude Code, é defeito do prompt: se ninguém deu a documentação como fonte e ninguém definiu o critério de validação, o agente preenche o buraco com o padrão mais provável que ele já viu na vida. Bora montar o prompt de integração passo a passo, do jeito que fecha esse buraco?

Por que o agente inventa campos e rotas que não existem

Existe dado sério sobre isso, e ele é desconfortável

Um estudo apresentado na USENIX Security 2025 analisou 576 mil amostras de código geradas por 16 LLMs em Python e JavaScript e encontrou 19,7% dos pacotes recomendados inexistentes, com 205.474 nomes de pacotes alucinados únicos

A média variou bastante por tipo de modelo: pelo menos 5,2% nos modelos comerciais e 21,7% nos modelos abertos

E tem uma parte que eu acho ainda mais reveladora: a alucinação se repete

Repetindo dez vezes 500 prompts que já tinham gerado pacotes falsos, 43% dos pacotes inventados reapareceram em TODAS as execuções e 58% apareceram em mais de uma

Ou seja, não é ruído aleatório que some se você rodar de novo, é um padrão estável na cabeça do modelo

Uma réplica de 2026 do mesmo método, com 199.845 prompts pareados em Python e JavaScript validados contra as listas do PyPI e do npm, mediu taxas entre 4,62% e 6,10% nos modelos avaliados. Melhorou bastante, beleza, mas não zerou

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 118 aulas
• 4 projetos
• 9h 33min

Conhecer formação

O que esses números querem dizer (e o que NÃO querem)

Seja honesto com o dado: esses percentuais são sobre nomes de pacote, não sobre endpoints de API

Ninguém mediu "quantos % das rotas inventadas" nesses estudos

Mas o mecanismo é o mesmo, e é aí que mora o sinal de alerta: quando o modelo não tem como conhecer um detalhe (porque a API é nova, privada, mudou de versão ou é interna da empresa), ele não trava e pergunta, ele completa com o que parece plausível

Nome de pacote plausível, nome de campo plausível, rota plausível

Se já é assim com pacote público (que tá no PyPI, no npm, no GitHub, no treino inteiro), imagina com a API que você nunca usou e a documentação que saiu mês passado, né?

A conclusão prática é simples: documentação lida na hora > memória do modelo

O que ter em mãos antes de abrir o prompt

Antes de digitar qualquer coisa, separa essas quatro coisas. Leva dois minutos e economiza uma tarde:

• A URL exata da página de referência da API: aquela que lista endpoints, autenticação e códigos de erro. Não a home do produto, não o blog de lançamento, a página de referência mesmo
• Uma credencial de teste: sandbox, chave de dev, o que a API oferecer
• Um endpoint barato pro primeiro teste real: algo como um GET simples que não cria, não cobra e não quebra nada se der errado (é ele que você vai usar lá no passo 7, a prova de que a integração existe de verdade)
• A decisão de onde as regras do projeto vão morar

Esse último item é o que a galera pula, e é o que faz a diferença da segunda integração em diante

Que regras do projeto? E onde elas moram?

O Claude Code lê arquivos CLAUDE.md no início de toda sessão, e é ali que vivem as instruções persistentes do projeto

É o lugar certo pra escrever coisas do tipo "nunca use um endpoint que não esteja na doc lida nesta sessão"

Só um cuidado que a própria documentação avisa: CLAUDE.md acima de 200 linhas consome mais contexto e pode piorar a aderência às instruções, e arquivo acima de 4 MiB é simplesmente ignorado

Então nada de despejar a API inteira lá dentro

Regra curta e afiada vale mais que manual gigante que o agente vai seguir pela metade

Passo a passo: o prompt de integração de API externa no Claude Code

A ordem aqui importa tanto quanto o texto

A ideia é: primeiro o agente entende, depois planeja, depois você aprova, ele escreve, e no fim a API real dá o veredito

1. Entre no plan mode antes de pedir qualquer coisa

No modo plano, o Claude Code lê arquivos, roda comandos de shell pra explorar e escreve um plano, mas não edita o código-fonte: as edições ficam bloqueadas até você aprovar o plano

Pra entrar, use Shift+Tab pra ciclar até o plan mode, ou prefixe o prompt com /plan

/plan Vamos integrar a API do Exemplo neste projeto.
Nesta etapa eu quero só entendimento e plano, nada de código.

O erro comum deste passo: pedir a integração no modo normal "só pra ver o que ele faz". Aí ele faz, cria seis arquivos, e agora você tá revisando código em vez de revisando premissa

2. Dê a documentação certa, não um link qualquer

Aqui tem uma distinção que muita gente confunde

O Claude Code tem duas ferramentas web diferentes: o WebSearch roda uma busca no backend da Anthropic e devolve títulos e URLs, sem baixar o conteúdo das páginas

Pra efetivamente LER uma página encontrada, ele usa depois o WebFetch, que lê uma URL específica

Traduzindo: mandar ele "pesquisar sobre a API X" não coloca a documentação no contexto, coloca só uma lista de links

O que você quer é apontar a URL exata:

Leia https://docs.exemplo.com/api/reference antes de qualquer coisa.
Depois me diga, com base SÓ nessa página:
1. como é a autenticação
2. quais endpoints resolvem o que eu preciso
3. quais códigos de erro a API documenta

Pra não ficar aprovando acesso a cada chamada, libere o domínio com o comando /permissions, que gerencia as regras de permissão, usando a sintaxe WebFetch(domain:exemplo.com)

E se liga em duas pegadinhas do casamento de domínio:

• WebFetch(domain:*.exemplo.com) cobre os subdomínios, mas não cobre o exemplo.com puro
• WebFetch(domain:exemplo.*) cobre variações de TLD

O erro comum deste passo: liberar *.docs.exemplo.com achando que pegou tudo, e depois ficar quebrando a cabeça porque a página raiz continua bloqueada

3. Anexe o contexto local com @arquivo

Descrever onde o código está é desperdício de prompt e fonte de suposição

No prompt do Claude Code você referencia arquivos com @ seguido do nome, e ele lê o arquivo antes de responder

O cliente HTTP do projeto está em @src/lib/http.ts
Os padrões de erro que usamos estão em @src/lib/errors.ts
Siga esses dois. Não crie um cliente novo.

O erro comum deste passo: escrever "use o padrão do projeto" sem anexar nada. O agente vai adivinhar qual é o padrão, e adivinhar é exatamente o que a gente tá tentando evitar aqui

4. Defina erro, timeout e limites ANTES do código

Esse passo é o que separa o cliente de API que aguenta produção do cliente que funciona só no dia bom

Se você não disser o que fazer quando a API devolver erro, o agente escolhe sozinho, e a escolha dele costuma ser otimista demais

Antes de escrever código, defina no plano:
- o que acontece em cada código de erro documentado na página que você leu
- o que acontece em timeout e em falha de rede
- se tem retry, quantas tentativas e com qual espera
- o que NUNCA deve ser repetido automaticamente (qualquer coisa que cria ou cobra)
- onde a credencial é lida e por que ela não pode aparecer em log

Sobre limite de requisição: pergunte ao plano o que a documentação diz, não deixe o agente estimar

Número de rate limit chutado é tão inventado quanto rota chutada

O erro comum deste passo: aceitar retry automático em endpoint de escrita. É assim que se cria três pedidos idênticos numa instabilidade de dois segundos. Já vi esse filme e não tem final feliz

5. Exija rastreabilidade: cada campo tem que estar na doc

Esse é O parágrafo do post, se você levar só um pedaço, leve esse

Regra obrigatória do plano:
cada endpoint, cada parâmetro e cada campo de resposta que você usar
deve aparecer na documentação que você leu nesta sessão.

Monte uma lista final "NÃO CONFIRMADO" com tudo que você assumiu
sem ter visto na doc.

Se essa lista não estiver vazia, não escreva código: me mostre a lista
e me diga exatamente o que falta confirmar.

A regra completa, em uma frase: nada entra no código sem estar na doc lida nesta sessão, e tudo que for suposição sai da geração e volta pra você em forma de pergunta

Repare no que isso faz: em vez de tentar impedir a alucinação (impossível), você obriga o agente a declarar onde ele está chutando

E aí o chute vira uma pergunta pra você responder, não um bug pra você caçar

O erro comum deste passo: não pedir a lista do que não foi confirmado. Sem ela, a suposição entra no código silenciosa, com aparência de fato

6. Aprove o plano e deixe gerar

Leu o plano, a lista de não confirmados tá vazia ou resolvida, beleza: aprova

Aprovar o plano sai do modo plano e muda a sessão para o modo de permissão descrito na opção de aprovação que você escolher, então preste atenção em qual opção você clica

E uma dica de escopo: peça a integração em fatias, não o pacote completo de uma vez. A mesma lógica de pedir a tela em partes ordenadas vale aqui: um endpoint funcionando inteiro ensina mais que seis endpoints meio prontos

O erro comum deste passo: aprovar o plano sem ler, no modo scroll rápido. O plano é justamente a parte barata de consertar, o código é a parte cara

7. Valide com uma chamada real, antes de seguir

Código de integração que nunca falou com o servidor é hipótese, não é integração

Esse passo é obrigatório, não é bônus: use aquele endpoint barato que você separou lá no começo e rode de verdade, com a credencial de teste

Rode uma chamada real contra a API usando a credencial de teste,
no endpoint mais barato possível.
Me mostre a resposta bruta, sem interpretar.

A resposta bruta é o ouro aqui: é ela que denuncia campo com nome diferente, envelope inesperado, data em outro formato

Só depois que a resposta real bateu com o que o plano prometeu é que a integração pode seguir pros próximos endpoints

Se você bateu o olho no diff e não entendeu metade do que mudou, vale revisar o diff com método antes de dar o commit

O erro comum deste passo: validar só com teste mockado. O mock foi escrito pelo mesmo agente que supôs os campos, então ele concorda com a suposição por construção. Mock não prova que a API existe do jeito que o código acha que existe

Quando vale plugar um MCP de documentação em vez de colar links

Colar URL no prompt funciona muito bem pra uma integração pontual

Agora, tem três cenários em que isso para de escalar:

• API grande: a referência está espalhada em dezenas de páginas e você não sabe de antemão qual delas tem o campo que importa
• Time inteiro repetindo a integração: cada dev colando um link diferente, cada um com um pedaço da verdade
• Documentação que muda: você libera o domínio, decora a página, e três semanas depois a rota mudou de lugar

Nesses casos, faz sentido trazer a documentação por um servidor MCP em vez de por link manual

O Context7 é um servidor MCP que entrega documentação de código atualizada pra LLMs e editores de IA. Ele é mantido pela Upstash, e o repositório oficial é upstash/context7

Como o registro de um servidor MCP funciona por aqui:

O comando claude mcp add grava os dados do servidor num arquivo de configuração e, por padrão, registra no escopo local: privado e só no projeto atual

Se você quiser mudar isso, tem duas flags:

• --scope user: vale pra todos os seus projetos
• --scope project: compartilha com o time

Variável de ambiente (chave de API do servidor, por exemplo) entra com --env CHAVE=valor no claude mcp add, ou no campo env da entrada em .mcp.json

E dentro da sessão, o comando /mcp gerencia os servidores já adicionados

Escolha o escopo pensando em quem precisa daquilo

Servidor que só você usa no projeto atual: deixa no padrão

Servidor que o time todo precisa pra reproduzir a mesma integração: --scope project, senão você vira o suporte técnico do seu próprio setup, haha

Como travar as regras para a próxima integração já nascer certa

Aqui é onde o trabalho vira permanente, e é a parte que quase ninguém faz

Você acabou de descobrir, na marra, quais regras impedem o agente de inventar API

Se elas ficarem só no histórico daquela conversa, semana que vem tá tudo de novo do zero

Regras de validação no CLAUDE.md

Como o CLAUDE.md é carregado no começo de cada conversa, é o lugar natural pra fixar o critério

Algo curto, do tipo:

## Integração com API externa
- Ler a página de referência da API com WebFetch antes de escrever código
- Nenhum endpoint, parâmetro ou campo pode ser usado sem aparecer na doc lida
- Listar explicitamente o que não foi confirmado, antes de gerar
- Sem retry automático em endpoint que cria ou cobra
- Validar com uma chamada real antes de seguir

Cinco linhas

Lembra do limite de 200 linhas: passar disso consome mais contexto e pode reduzir a aderência, então entra ali só o que é regra de verdade, não documentação de API

A memória automática, pelo /memory

O Claude Code também mantém uma memória automática, com notas que ele mesmo escreve a partir das suas correções

O comando /memory abre essa pasta de auto memory, em markdown editável

Vale dar uma passada de olho de vez em quando: se ele registrou alguma conclusão errada sobre a sua API, você edita ali mesmo

Os escopos de permissão

As regras de permissão vivem em arquivos diferentes, com escopos e precedência distintos:

Na prática: domínio de documentação que o time inteiro precisa (a referência oficial da API que vocês integram) vai pro arquivo versionado

Aquele domínio que só você consulta fica no .claude/settings.local.json

E quando permissão não basta?

Além das regras e dos modos de permissão, um hook PreToolUse é uma das formas de conceder ou revogar acesso a uma chamada de ferramenta

Ele bloqueia a chamada antes dela rodar

É a camada certa quando você precisa de uma checagem programável, e não só de uma lista de domínios permitidos

Conclusão

No fim, integrar API que você nunca usou com agente se resume a quatro princípios, e nenhum deles é prompt mágico:

documentação como fonte (WebFetch na URL certa, não memória do modelo)

plano antes do código (plan mode, com o que não foi confirmado escrito na cara)

critério de erro definido por você (erro, timeout e limite decididos antes da geração)

chamada real como prova (resposta bruta do servidor, não mock que concorda com a suposição)

Os 19,7% de pacotes inexistentes do estudo da USENIX não são um motivo pra desconfiar da ferramenta, são um motivo pra mudar o prompt: o agente completa buraco, então não deixe buraco

Próximo passo bem concreto: pega a API da sua próxima tarefa, libera o domínio da documentação dela no /permissions e roda o primeiro prompt em plan mode

Se a lista de "não confirmado" voltar cheia, ótimo: você acabou de ver, de graça, tudo que teria virado bug 😀

Até o próximo post!