Mods, hooks ou MCP no Claude Code: qual camada usar para cada problema?

O erro mais comum hoje não é escolher a ferramenta ruim

É escolher a camada errada pra resolver o problema

Fala aí, beleza? Em 1º de outubro de 2026, junto com a versão 2.1.287, a Anthropic lançou os mods no Claude Code 🙂

Aí o Claude Code passa a ter três jeitos de mudar o comportamento do agente: mods, hooks de configuração e servidores MCP

E cada um ataca um tipo BEM diferente de problema

Se tu usa um hook pra resolver falta de dado externo, ou um MCP pra algo que era só automação, vai sofrer à toa… bora separar isso direito?

O que são mods no Claude Code e o que mudou na v2.1.287

Um mod é um plugin cujo código registra handlers de evento que rodam dentro do próprio Claude Code

São funções em TypeScript ou JavaScript, rodando no mesmo processo do agente

Se você conhece middleware de servidor web, a ideia é bem parecida: o evento passa pela sua função antes de seguir o caminho dele

O que mudou na v2.1.287:

• Os mods vêm ligados por padrão na v2.1.287 ou superior
• A variável CLAUDE_CODE_ENABLE_FUNCTION_HOOKS, usada no acesso antecipado, passou a ser ignorada (definir como 0 NÃO desliga os mods), então pode remover ela
• Funcionam no CLI e no app desktop do Claude Code
• Vêm dentro de plugins e são instalados com /plugin no CLI
• Quatro mods já vêm embutidos, entre eles o /diff e um que carrega o AGENTS.md como instruções do projeto

Mod tem hook, mas não é o hook de configuração

Aqui mora a confusão de nomes, se liga nisso

Os handlers de evento de um mod também se chamam hooks

Só que eles NÃO são os hooks de configuração (os clássicos, que você define em settings.json)

Hook de mod é código rodando dentro do Claude Code, hook de configuração é uma ação disparada num evento do ciclo de vida

Guarda essa diferença porque o resto do post depende dela 😀

Mods vs hooks vs MCP: comparação lado a lado

Quando usar hooks de configuração

Hook é a escolha quando a ação precisa acontecer SEMPRE do mesmo jeito e não depende do raciocínio do Claude

Os exemplos da própria documentação:

• Formatar o arquivo ao salvar
• Bloquear rm -rf / (os rm -rf da vida, né? haha)
• Mandar mensagem no Slack quando a sessão termina

O hook executa um comando de shell, um request HTTP, uma chamada de ferramenta MCP, um prompt de LLM ou um subagente quando o evento acontece

E como ele sempre dispara, você não fica dependendo do modelo "lembrar" de fazer a coisa

O que dá pra fazer com o PreToolUse?

O PreToolUse roda depois que o Claude monta os parâmetros da ferramenta e antes de executar

Ele pode:

• Decidir a chamada pelo campo permissionDecision: allow, deny, ask ou defer
• Reescrever os argumentos com updatedInput

O matcher filtra pelo nome da ferramenta, tipo Bash, Edit|Write ou mcp__.*

Tome cuidado: o matcher diferencia maiúsculas de minúsculas, então bash não é Bash

A pegadinha do @ no prompt

Arquivos que você referencia com @ no prompt NÃO disparam o PreToolUse

Ou seja, se o seu hook de bloqueio depende de ver a leitura do arquivo, ele não vai pegar esse caso

Onde configurar hooks:

• ~/.claude/settings.json: vale pra todos os projetos
• .claude/settings.json: vale pra um projeto
• .claude/settings.local.json: um projeto, fora do git
• Managed policy settings: nível de organização
• hooks/hooks.json dentro de um plugin
• Frontmatter de skill ou subagente

E pra conferir o que já está ativo, roda /hooks

Quando usar um servidor MCP

MCP (Model Context Protocol) é um padrão open source que conecta o Claude Code a ferramentas externas, bancos de dados e APIs

Então a pergunta é simples: o problema é falta de ACESSO?

Se o Claude precisa ler o Notion, mexer num navegador ou consultar um banco, nenhuma instrução e nenhum hook resolvem isso, ele precisa da conexão

Se quiser ir mais fundo no conceito, tenho um post sobre o que são servidores MCP e quando eles valem a pena

Como adicionar um servidor MCP:

Servidor remoto, passando o transporte HTTP e a URL:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Servidor local, passando o comando depois do --:

claude mcp add playwright -- npx -y @playwright/mcp@latest

Escopos do MCP: local, user ou project?

• local (padrão): privado, só no projeto atual
• --scope user: vale pra todos os seus projetos e grava em ~/.claude.json
• --scope project: compartilhado com o time pelo .mcp.json na raiz do projeto

O erro típico com MCP

Tentar resolver com hook ou com instrução algo que, na real, é falta de dado externo

Você escreve no CLAUDE.md "use sempre a API mais recente da biblioteca X"… mas o modelo não TEM essa API mais recente, então a instrução não adianta nada

Na prática: o Context7 como servidor MCP para ler a documentação antes de codar

Esse é o caso perfeito pra ver a camada certa funcionando

O problema era dado externo: documentação atualizada de biblioteca

No vídeo abaixo eu mostro o Context7 rodando como servidor MCP num projeto Next.js que já existia, com rotas protegidas por autenticação

O que eu fiz:

• Instalei o MCP do Context7 no Claude Code pelo terminal e reiniciei o Claude Code pra confirmar a conexão
• Pedi pro agente verificar se as rotas protegidas estavam configuradas certinho, mandando ele usar o Context7 no próprio prompt

E o resultado foi mto massa:

• As rotas, individualmente, estavam OK
• Mas as rotas de API não entravam no match do middleware
• E uma rota específica não tinha as subrotas protegidas no middleware

Ele ainda sugeriu uma verificação de API no middleware como camada extra de segurança, avaliando que o risco atual era baixo porque cada rota de API já checava autenticação por conta própria

Na minha visão, esse tipo de sugestão só apareceu porque o agente tinha a documentação atualizada na mão

Sem isso, não aconteceria

E a skill, onde entra?

No vídeo eu também testo o outro modo do Context7: gerar uma skill a partir de um comando de terminal separado do MCP

Descrevi a expertise que eu queria (Next.js, boas práticas de arquitetura e padrões de design) e usei a skill pra criar uma página de contato mantendo o design system do projeto

A página saiu seguindo os padrões visuais e de arquitetura que o projeto já tinha 😀

Minha opinião sincera:

• Pro dia a dia, prefiro skill, porque fica salva e evita chamada repetida ao MCP, consumindo menos contexto
• MCP brilha quando o projeto alterna entre tecnologias (frontend e depois backend, por exemplo), porque o dado vem atualizado a cada prompt
• Cuidado: a skill fica presa na versão da doc do momento em que foi gerada, só atualiza se você pedir

O que eu faço: gero as skills das tecnologias do projeto logo no início e reaproveito em toda página ou funcionalidade nova

Uma não substitui a outra, cada uma tem seu momento

Quando usar mods (e o cuidado com segurança)

Mod é pra quando você quer mexer no PRÓPRIO agente, por dentro

O que um mod consegue fazer:

• Reescrever um prompt
• Adicionar UI nova, como um painel ao lado do transcript ou uma faixa acima do prompt
• Redesenhar partes da interface do Claude Code
• Segurar uma tool call pra perguntar algo ao usuário
• Responder sem executar a ferramenta
• Mandar um request pra outro modelo
• Criar um /comando que roda uma função sem passar por um turno do Claude

Como funciona o handler de um mod?

O registro é feito com on(eventName, handler)

O handler recebe três coisas: a API de mods ($), o evento (e) e o próximo handler (next)

E aí ele tem três caminhos:

• Observar: retorna next(e) e deixa tudo seguir
• Reescrever: chama next com uma cópia alterada do evento
• Responder no lugar: retorna um resultado sem chamar next, e o Claude Code nem chega a executar

Os exemplos que a Anthropic publicou mostram bem a pegada:

• token weather: medidor de contexto
• blast radius: prévia do que vai ser apagado
• replay theater: replay das edições passo a passo

Tome cuidado com mod de origem duvidosa!

Mod roda SEM sandbox, com o mesmo acesso à máquina que o próprio Claude Code

Isso significa que ele:

• Lê e grava arquivos onde a sua conta tem acesso
• Lê variáveis de ambiente e arquivos de configuração, incluindo chaves de API
• Vê todos os prompts e tool calls
• Gasta o seu uso

Então nada de sair instalando mod aleatório porque o painel ficou bonito haha

Instala só de origem confiável

Veredito: como escolher a camada certa sem errar

Uma correção antes: tem gente tratando mod como a camada de "instrução", e não é

Pela documentação, mod é código que intercepta evento e desenha interface

Instrução e contexto ficam com CLAUDE.md e skills

Agora a regra de decisão em perguntas:

1. O Claude precisa de um dado que não tem (ferramenta, banco, API, doc atualizada)? Servidor MCP
2. Precisa acontecer sempre, igual, num evento (formatar, bloquear, notificar)? Hook de configuração
3. Precisa mudar como o agente se comporta ou se apresenta por dentro (prompt, tool call, interface)? Mod
4. É contexto ou instrução? CLAUDE.md se tem que estar sempre ativo, skill se é conhecimento ou workflow sob demanda

A própria doc divide assim: CLAUDE.md pra contexto sempre ativo, skills pra conhecimento sob demanda, MCP pra conexões externas, subagentes pra isolamento e hooks pra automação

E setups reais combinam várias camadas, isso é o normal

Vale tanto pra dev quanto pra quem usa o Claude Code sem programar em tarefa repetitiva: o raciocínio de "qual tipo de problema é esse?" é o mesmo

Conclusão

A escolha entre mods, hooks e MCP no Claude Code é pelo tipo de problema, não pela ferramenta mais nova

Dado externo é MCP, automação determinística é hook, mudar o agente por dentro é mod, e instrução é CLAUDE.md ou skill

Próximo passo concreto:

1. Roda /hooks e vê o que já está ativo no seu setup
2. Lista um problema que tu tem hoje com o agente
3. Classifica em instrução, automação ou dado externo antes de instalar qualquer mod ou servidor MCP

Faz o teste, é rápido e evita muiiita dor de cabeça 🙂

Até o próximo post!