Context7 MCP no Claude Code: como parar de receber código de uma versão antiga da biblioteca

Fala aí, beleza? Sabe aquele código lindo que o agente entrega, tu roda e ele quebra no primeiro run? O parâmetro mudou de nome, o import saiu da lib, o método virou outra coisa

Não é bug do teu projeto, é o modelo respondendo com a versão da biblioteca que ele memorizou lá atrás

O Context7 é um servidor MCP mantido pela Upstash que ataca exatamente esse ponto: ele pega a documentação oficial atual da biblioteca e injeta os trechos no contexto do Claude Code antes do agente escrever a primeira linha

Aqui tu vai ver o porquê do erro, o passo a passo de instalação, o que muda de verdade na resposta do agente, em que stack isso rende (e onde não faz diferença nenhuma) e quanto custa

Por que o Claude Code escreve código de uma versão antiga da biblioteca

O sintoma: o código parece certo e não roda

É sempre o mesmo padrão

Um import que não existe mais, um parâmetro renomeado, uma opção de config que saiu na virada de major, um exemplo que era o jeito certo de fazer há dois anos

O pior caso é o método que nunca existiu: o modelo junta duas APIs parecidas e te entrega uma terceira, plausível e falsa

Aí tu gasta token pedindo o fix, o agente vai pesquisar, volta, tenta de novo… e o ciclo se paga em contexto queimado

A causa: memória não é documentação

O modelo não abre o site do pacote quando responde

Ele responde do que absorveu no treino, e biblioteca que atualiza rápido (React, Next, ORMs da vida) envelhece MUITO mais rápido que o corte de treino

Quanto mais o teu projeto depende de uma release específica, maior a chance da resposta bater em outra

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

A solução: uma fonte que dá pra consultar na hora

É aqui que entra o MCP de documentação

O servidor do Context7 expõe duas ferramentas usadas em sequência: resolve-library-id, que converte o nome da biblioteca num ID compatível com o Context7, e query-docs, que busca a documentação daquela biblioteca usando esse ID

A ordem importa: é preciso chamar resolve-library-id antes, a menos que tu já informe o ID direto

E o ID aceita fixar versão, no formato /org/project ou /org/project/version

Se liga nisso, porque é o detalhe mais útil do recurso todo: projeto travado numa release específica pode apontar a documentação pra ELA, não pra última

Como prevenir: uma regra no CLAUDE.md

Gatilho manual funciona, mas tu vai esquecer

O jeito de virar hábito é escrever no CLAUDE.md uma regra instruindo o agente a consultar a documentação atual sempre que a tarefa envolver biblioteca, framework ou SDK de terceiro, passando por resolve-library-id e depois query-docs

Esse tipo de instrução é citado na documentação e nas issues do projeto, e é o que transforma o Context7 de "lembrei de usar" em comportamento padrão do agente

O que você precisa antes de instalar o Context7

A lista é curta, mas cada item evita uma dor de cabeça depois

• Claude Code funcionando na máquina onde tu vai codar
• Saber que a autenticação muda de forma conforme o caminho de instalação: no plugin, sem API key a conexão é anônima e divide os limites anônimos com o resto do mundo. Pra usar o teu plano nesse caminho, tu cria uma API key no dashboard do Context7 e exporta ela como variável de ambiente ANTES de abrir o Claude Code. Já quando tu adiciona o servidor MCP HTTP na mão, a key não vai por variável de ambiente: ela entra no próprio comando, no --header
• Saber quando a autenticação é obrigatória: ela é opcional pra documentação pública e obrigatória pros recursos Pro/Enterprise, tipo repositório privado, políticas de teamspace e limites maiores
• Conferir se a tua biblioteca está indexada: as indexadas ficam em context7.com/libraries e a fila de processamento em context7.com/tasklist

Detalhe pequeno que salva tempo: as API keys do Context7 têm prefixo fixo ctx7sk-

Se o que tu colou não começa assim, não é key 🙂

Como instalar e usar o Context7 MCP no Claude Code (passo a passo)

Tem mais de um caminho, e eles não são equivalentes. Vou do recomendado pro alternativo

1. Instale pelo plugin do marketplace oficial (recomendado)

Dentro do Claude Code, roda:

/plugin marketplace add upstash/context7
/plugin install context7@context7-marketplace

Esse plugin traz mais que o servidor MCP: vem uma skill que dispara a busca de documentação automaticamente quando tu pergunta sobre bibliotecas, agentes pra consultas focadas e o comando /context7:docs pra consulta manual

Detalhe da autenticação NESTE caminho: sem API key o plugin conecta de forma anônima e divide os limites anônimos. Pra usar o teu plano, cria a key no dashboard do Context7 e exporta ela como variável de ambiente antes de abrir o Claude Code

Erro comum deste passo: procurar o projeto no GitHub e cair no upstash/context7-legacy, que é um repositório distinto do atual. A plataforma de hoje é upstash/context7

2. Ou adicione como servidor MCP HTTP, com a sua API key no comando

claude mcp add --header "CONTEXT7_API_KEY: YOUR_API_KEY" --transport http context7 https://mcp.context7.com/mcp

Repara na diferença pro passo 1: aqui a key vai literal no comando, dentro do --header. O caminho da variável de ambiente é o do plugin, não é este

Erro comum deste passo: deixar o YOUR_API_KEY literal no comando, ou colar algo que não começa com ctx7sk-

3. Ou sem colocar API key nenhuma, pelo endpoint OAuth

claude mcp add --transport http context7 https://mcp.context7.com/mcp/oauth

Aqui tu não passa header nenhum: o endpoint termina em /mcp/oauth justamente porque a autenticação acontece pelo fluxo OAuth, e não por uma key colada no comando

Erro comum deste passo: trocar os endpoints. O https://mcp.context7.com/mcp/oauth é o do passo 3; o https://mcp.context7.com/mcp é o do passo 2, que espera a key no header

4. Ou use o instalador CLI interativo

npx ctx7 setup

Ele abre um assistente que cuida da autenticação e da configuração em vários clientes

A autenticação usa OAuth device flow (link de verificação mais um código curto), então funciona também em host remoto, headless ou via SSH

Erro comum deste passo: partir pra gambiarra de túnel achando que precisa de navegador na máquina remota. Não precisa, o device flow existe pra isso

5. Use no dia a dia

O gatilho manual clássico é escrever use context7 no fim do prompt: o servidor identifica a biblioteca, busca a documentação oficial atual e injeta os trechos no contexto do modelo

Com o setup via ctx7 ou via skill do plugin, o disparo é automático quando tu pergunta sobre bibliotecas

E pra consulta manual e direta, tem o /context7:docs

Erro comum deste passo: seguir tutorial antigo que manda chamar get-library-docs. Essa ferramenta foi renomeada pra query-docs na versão 2.0.0 do pacote @upstash/context7-mcp, publicada em 29/12/2025

Outro erro comum: chamar query-docs sem resolver o ID antes

6. Automatize com uma regra no CLAUDE.md

Sempre que a tarefa envolver biblioteca, framework ou SDK de terceiro,
consulte a documentação atual pelo Context7 antes de escrever código:
chame resolve-library-id e depois query-docs.
Quando o projeto estiver travado numa release, use o ID no formato /org/project/version.

Erro comum deste passo: escrever a regra e nunca fixar a versão. Se o teu projeto não está na última release, o ID sem versão te devolve documentação certa da biblioteca errada pro teu caso

Como foi na prática: o que muda na resposta do agente

No vídeo eu adicionei o MCP pelo terminal, confirmei a instalação, reiniciei o Claude Code e fui conferir na listagem de MCPs se o servidor aparecia conectado

Parece besteira esse último passo, mas é ele que separa "instalei" de "está funcionando"

Depois testei num projeto Next meu que tem rotas protegidas: pedi pro agente verificar se a proteção estava configurada corretamente e fechei o prompt mandando ele usar o Context7

O retorno veio com coisa concreta, não com papo genérico: rotas de API fora do matcher do middleware e uma rota com subrotas não cobertas pela proteção

A conclusão dele foi que a configuração estava funcionalmente correta e o risco atual baixo, já que cada rota de API verifica autenticação individualmente

Esse tipo de sugestão de melhoria eu não vejo o agente entregar sem a documentação atualizada do lado dele

Agora a parte chata: com o MCP, o agente bate na API a cada consulta, e isso inevitavelmente gasta mais token

Por isso eu prefiro o outro caminho, que é gerar uma skill DA TECNOLOGIA

E atenção pra não confundir com a skill que vem no plugin do passo 1: aquela é do próprio Context7 e serve pra disparar a busca de documentação, ou seja, ela continua chamando o servidor. A que eu falo aqui é outra coisa, um arquivo com o conhecimento já destilado dentro dele

A skill fica salva localmente pra sempre, o agente lê o arquivo em vez de fazer o ciclo de ida e volta do MCP, e consome menos contexto. Se tu já mexeu com o Superpowers do Claude Code, a lógica é a mesma: conhecimento em arquivo que o agente carrega quando precisa

A contrapartida é honesta: a skill é fixa e só atualiza se tu pedir, então ela serve bem pra versão atual do projeto e envelhece com o tempo

Rodei o gerador de skills direto no terminal, fora do MCP, e precisei fazer login antes de continuar

Ele faz uma sequência de perguntas, com exemplos de como descrever uma boa expertise. Eu escrevi a descrição em inglês, pedi uma skill de Next voltada a criação de componentes e features e escolhi foco em padrões de arquitetura pra escalabilidade

No fim ele perguntou onde instalar, detectou o projeto que eu tinha aberto e instalou ali mesmo

Fui ler o arquivo gerado: bem técnico, com boas práticas de criação de componentes e critério de decisão entre server e client component

Com a skill instalada, pedi uma página nova estilizada seguindo o visual do projeto e a página de contato saiu mantendo o design system existente, sem eu ficar explicando o padrão de novo

Recomendação prática: se tu tem muitas páginas pra criar, a skill da tecnologia compensa mais que o MCP, porque cada uso evita uma nova batida no servidor

A estratégia que eu sigo é gerar as skills das tecnologias no início do projeto e depois só reutilizar a cada nova feature ou página

No vídeo acima tu vê o setup do MCP no terminal, a checagem das rotas protegidas do projeto Next com o retorno do agente na tela, o gerador de skills perguntando por perguntando, e a página de contato criada no fim

Em que stack o Context7 rende mais (e quando não faz diferença)

Vamos ser justos com a ferramenta: ela não é mágica, é índice de documentação. Onde tem índice bom, ela brilha

Rende mais em:

• bibliotecas populares e bem indexadas, que é onde a cobertura é boa
• SDKs que quebram API entre versões, o caso clássico do agente gerar código de uma versão anterior à que o projeto usa
• projeto travado numa versão específica, usando o ID no formato /org/project/version
• monorepo com dependências que o time atualiza pouco, onde a última documentação da internet é justamente a errada pra ti

Rende pouco em:

• pacote de nicho que não está no índice
• release muito recente, ainda não indexada
• código sem dependência de terceiro: lógica própria, SQL, script interno. Aqui não tem documentação externa pra buscar, o gargalo é outro

O índice acompanha e atualiza sozinho as bibliotecas já indexadas

Mas se a que tu usa não está lá, tu precisa adicionar: dá pra fazer pela interface web em context7.com/add-library, pelos endpoints da API REST pública ou incluindo um arquivo context7.json no repositório

Antes de brigar com o setup achando que quebrou, dá uma olhada na fila em context7.com/tasklist. Às vezes a lib só está esperando a vez

Free ou Pro: limites e preço do Context7

Atenção no cálculo de time: cada membro (Owner, Admin ou Developer) conta como um assento

E repara que o limite de 60 requisições por hora vale pros dois planos, então plano pago não é passe livre pra rajada

Um histórico que vale conhecer antes de montar o teu fluxo em cima do Free: em 13/01/2026 o plano gratuito caiu de cerca de 200 requisições por dia (aprox. 6.000 por mês) para 500 por mês, e em 16/01/2026 foi reajustado pra 1.000 por mês, que é o valor vigente

Ou seja: o Free existe e dá pra trabalhar, mas já mudou de tamanho no meio do caminho

Vale a pena colocar o Context7 no seu Claude Code?

Vale, com expectativa calibrada

O Context7 resolve UM problema, e resolve bem: colocar a documentação atual da biblioteca dentro do contexto antes do agente codar

Ele não resolve arquitetura ruim, não acha bug de lógica e não substitui revisão. Se o teu agente está te entregando código que passa mas não prova nada, o remédio é outro, tipo pedir testes ao Claude Code do jeito certo

E tem o limite honesto da cobertura: se a tua stack vive de pacote de nicho, o índice pode não ter o que tu precisa, e aí o ganho some

Próximo passo concreto, na ordem: instala pelo plugin do marketplace, escreve a regra no CLAUDE.md e confere se as bibliotecas do teu projeto estão indexadas

Depois disso, se tu for criar várias páginas ou features da mesma tecnologia, considera gerar a skill da tecnologia e economizar as idas ao servidor

Sinal de que o projeto está em movimento: o pacote @upstash/context7-mcp está na versão 4.0.2, publicada cerca de 6 dias antes desta publicação

Testa aí no teu projeto e vê se o agente para de inventar API que não existe 😀

até o próximo post!