Documentação de Plugins do Claude Code: O Que São, Como Instalar e Quando Usar MCP

Se você está procurando a documentação de plugins do Claude Code, a resposta curta é: plugins são a camada de empacotamento para extensões do Claude Code. Um plugin pode agrupar skills, agents, hooks, servidores MCP, servidores LSP e monitores em uma unidade instalável, enquanto o MCP continua sendo a camada de conexão de ferramentas subjacente. Se você pesquisou por “mcp plugin” ou “doc plugin”, geralmente essa é a divisão que a documentação quer que você entenda: plugins distribuem a configuração, MCP conecta as ferramentas, e a documentação de referência explica a forma técnica de cada parte.

O Claude Code agora tem uma superfície de extensão grande o suficiente para que a terminologia possa ficar confusa rapidamente. “Plugin” é frequentemente usado como abreviação para tudo, mesmo quando o recurso real em jogo é uma skill, um hook ou um servidor MCP. Essa confusão é relevante porque as etapas de instalação, o modelo de segurança e o custo de manutenção são diferentes para cada um.

Antes de entrarmos na configuração, uma observação prática para equipes que desejam mais flexibilidade no backend do que um fluxo de trabalho apenas com modelos fechados: a camada de extensão do Claude Code é separada do modelo que você executa por trás. Isso significa que você pode manter a mesma configuração de plugin, skill e MCP enquanto roteia a inferência por meio de um modelo de código de peso aberto na Novita AI, como qwen/qwen3-coder-480b-a35b-instruct, que é uma opção viável para trabalho real em repositórios quando você deseja mais controle de custos sem abrir mão de ferramentas agentivas.

O Que a Documentação Atual Enfatiza

A documentação atual do Claude Code separa quatro coisas de forma muito clara:

• plugins, que empacotam extensões reutilizáveis;
• MCP, que conecta o Claude Code a ferramentas e fontes de dados externas;
• skills e subagents, que contêm comportamentos reutilizáveis;
• hooks, que automatizam ações em eventos do ciclo de vida.

Isso significa que muitas pesquisas por “documentação de plugins do Claude Code” na verdade estão pedindo a referência de plugins, o fluxo de descoberta/instalação, ou a documentação do MCP que explica como a conectividade de ferramentas funciona. A documentação atual também expõe fluxos de instalação e distribuição baseados em marketplace, permitindo instalar plugins pré-construídos em vez de configurar manualmente cada componente.

O Que São Realmente os Plugins do Claude Code

A documentação atual da Anthropic define plugins como a camada de distribuição e reutilização para extensões do Claude Code. Na prática, isso significa que um plugin é um diretório autocontido com um manifesto e componentes de extensão opcionais, como:

• skills
• agents
• hooks
• configuração MCP
• configuração LSP
• binários auxiliares
• configurações padrão

É por isso que a documentação oficial de plugins é importante mesmo se o que você realmente deseja é uma skill reutilizável ou um scaffold MCP de comando único. O plugin é frequentemente a coisa que você instala, mas o comportamento que lhe interessa vive dentro dos componentes empacotados.

A consequência mais importante é a nomenclatura. As skills de um plugin têm namespace, então um comando de um plugin se parece com isto:

/meu-plugin:hello

Esse namespace não é cosmético. Ele previne colisões entre plugins que enviam comandos com nomes semelhantes.

Plugins vs MCP vs Skills vs Hooks

É aqui que a maioria dos desenvolvedores perde tempo na documentação.

Use este atalho:

Recurso	O que faz	Melhor caso de uso
Plugin	Empacota e distribui extensões	Reutilizar a mesma configuração entre projetos ou colegas de equipe
MCP	Conecta o Claude Code a ferramentas e serviços externos	GitHub, Notion, bancos de dados, controle de navegador, APIs internas
Skill	Dá ao Claude conhecimento reutilizável ou um fluxo de trabalho	Checklists de revisão, fluxos de deploy, estilo da casa, prompts repetíveis
Hook	Executa automaticamente em eventos do ciclo de vida	Lint após edições, bloquear comandos arriscados, disparar notificações

Muitas perguntas sobre “plugin do Claude Code” são na verdade perguntas sobre MCP. Se seu objetivo é “conectar o Claude Code ao Jira” ou “deixar o Claude consultar nosso banco de dados”, você não está principalmente procurando um recurso de plugin. Você está procurando um servidor MCP, que pode ser instalado diretamente ou empacotado dentro de um plugin. Na prática, isso significa que muitas buscas por um MCP plugin são na verdade buscas pelo servidor certo mais o caminho de empacotamento ou instalação.

É também por isso que a visão geral de recursos na documentação da Anthropic é útil: ela separa explicitamente plugins de MCP e de skills. Plugins são o invólucro. MCP é a conexão externa. Skills são as instruções reutilizáveis. Hooks são a camada de automação.

De uma perspectiva de stack da Novita, este também é o lugar mais limpo para separar raciocínio de execução. Se você está construindo um fluxo de trabalho personalizado adjacente ao Claude Code em torno de ferramentas MCP, a API LLM da Novita pode lidar com a camada de raciocínio de uso de ferramentas enquanto o Novita Agent Sandbox lida com a camada de execução isolada para código, comandos de shell e efeitos colaterais de ferramentas. Essa divisão mapeia naturalmente para a fronteira “modelo decide” versus “runtime executa” que a documentação de plugins e MCP está realmente descrevendo.

Quando Você Deve Usar um Plugin

Use um plugin quando pelo menos uma das seguintes condições for verdadeira:

• você deseja a mesma personalização do Claude Code em vários repositórios;
• você quer que colegas de equipe instalem uma coisa em vez de copiar arquivos .claude/ manualmente;
• você deseja empacotamento versionado e compartilhável para skills, hooks ou configs MCP;
• você planeja distribuir a extensão por meio de um marketplace.

Não recorra a um plugin primeiro se você estiver apenas experimentando em um repositório. A documentação da Anthropic ainda recomenda começar com a configuração .claude/ independente para iteração rápida. Esse é o caminho de menor atrito para fluxos de trabalho específicos de projeto.

Em outras palavras:

• configuração independente é melhor para experimentação local;
• plugins são melhores para portabilidade e distribuição.

A Maneira Mais Rápida de Instalar um Plugin Existente

Se você já sabe o nome do plugin e o marketplace, a documentação atual aponta para o fluxo de comando slash de dentro do Claude Code.

Por exemplo, a documentação MCP da Anthropic usa este caminho de instalação para o plugin oficial mcp-server-dev:

/plugin install mcp-server-dev@claude-plugins-official

Se o Claude Code informar que o marketplace está faltando, adicione-o primeiro:

/plugin marketplace add anthropics/claude-plugins-official

Em seguida, execute novamente o comando de instalação.

Após a instalação, verifique se o Claude diz para recarregar os plugins. Se sim, execute:

/reload-plugins

Essa etapa de recarregamento é mais importante do que parece. É uma razão comum para desenvolvedores acharem que um plugin “não funcionou” quando os arquivos estão presentes mas os comandos não estão ativos na sessão atual.

Como Criar Seu Próprio Plugin do Claude Code

Se você deseja construir seu próprio plugin, a documentação atual de plugins descreve um quickstart direto:

1. Crie um diretório para o plugin.
2. Adicione .claude-plugin/plugin.json.
3. Adicione um diretório skills/, agents/, hooks/, ou outro diretório de extensão suportado.
4. Inicie o Claude Code com --plugin-dir durante o desenvolvimento.

O menor exemplo útil é um plugin que envia uma skill. A documentação da Anthropic mostra um manifesto mais uma pasta skills/<nome>/SKILL.md. O manifesto define a identidade do plugin, e a skill se torna um comando com namespace.

Durante o desenvolvimento, o fluxo de teste canônico é:

claude --plugin-dir ./meu-primeiro-plugin

Em seguida, invoque a skill de dentro do Claude Code:

/meu-primeiro-plugin:hello

Um detalhe que é fácil de perder: apenas plugin.json pertence dentro de .claude-plugin/. Seus diretórios skills/, agents/ e hooks/ ficam na raiz do plugin, não aninhados sob .claude-plugin/.

Por Que a Documentação Menciona MCP Dentro dos Guias de Plugin

Porque um plugin pode enviar uma configuração MCP.

Isso é útil quando você tem um serviço interno que todo engenheiro da sua equipe precisa que o Claude Code alcance. Em vez de dizer a todos para configurarem manualmente o mesmo servidor MCP, você pode empacotar essa configuração com o resto do seu fluxo de trabalho no Claude Code.

Isso não torna o MCP obsoleto. Apenas muda como o servidor é entregue.

Pense desta forma:

• MCP responde: “Como o Claude conversa com este sistema externo?”
• Um plugin responde: “Como distribuímos essa configuração de forma limpa?”

Se você está projetando uma plataforma interna para desenvolvedores, essa distinção economiza muito trabalho de configuração duplicado.

Quando o MCP É o Melhor Ponto de Partida

Comece com MCP, não com um plugin, quando o principal requisito for acesso externo:

• rastreadores de issues
• ferramentas de monitoramento
• Slack
• Notion
• bancos de dados
• automação de navegador
• serviços HTTP internos

A documentação atual do MCP da Anthropic mostra quatro modos comuns de conexão:

• servidores HTTP remotos
• servidores SSE remotos
• servidores stdio locais
• servidores WebSocket remotos

Para a maioria dos serviços em nuvem, HTTP é o transporte recomendado. SSE ainda é documentado, mas a Anthropic o marca como obsoleto onde HTTP está disponível.

Se você só precisa conectar um serviço para si mesmo, claude mcp add geralmente é o lugar mais limpo para começar. Empacote-o em um plugin mais tarde se a configuração se mostrar reutilizável.

MCP dá ao Claude Code uma maneira de alcançar ferramentas, mas não substitui um runtime de execução segura quando uma dessas ferramentas precisa executar código, tocar em arquivos ou executar comandos. Nessa configuração, a API LLM da Novita é o backend de raciocínio que decide quando e como chamar as ferramentas, enquanto o Novita Agent Sandbox é o ambiente de execução mais seguro para o lado do fluxo de trabalho que executa código. Se seu plugin ou servidor MCP está expondo execução remota de código, automação de navegador ou ajudantes baseados em shell, essa separação é mais do que higiene de arquitetura. É a diferença entre “Claude pode chamar esta ferramenta” e “esta ferramenta executa em um runtime isolado em vez de no laptop de um engenheiro ou em um host compartilhado.”

Uma Regra de Decisão Prática

Se você ainda não tem certeza de qual página da documentação realmente precisa, use esta regra:

• “Quero que o Claude Code faça algo da mesma forma em toda sessão.” Comece com CLAUDE.md ou uma skill.
• “Quero que o Claude Code converse com outro sistema.” Comece com MCP.
• “Quero que esta configuração seja fácil de reutilizar ou compartilhar.” Empacote como um plugin.
• “Quero que algo seja executado automaticamente em um evento.” Use um hook.

Isso é mais útil do que memorizar nomes de recursos porque mapeia diretamente para o problema que você está resolvendo.

Onde Isso Se Encaixa em um Fluxo de Trabalho Real

Se a configuração de plugin ou MCP é apenas uma peça de um stack agente maior, combine-a com O Que São Agentes de Codificação?, Runtime de Agente vs Interpretador de Código e Sandbox de Servidor MCP: Servidores MCP Isolados com Sistema de Arquivos, Segredos e Controles de Rede. Isso lhe dá a cadeia completa, do planejamento ao acesso de ferramentas e à execução isolada.

Um Bom Fluxo de Trabalho de Plugin para Equipes Reais

Para a maioria das equipes, a progressão mais limpa se parece com isto:

1. Prototipe o fluxo de trabalho em .claude/ ou com comandos diretos claude mcp add.
2. Mantenha apenas as partes que se mostram úteis no trabalho real.
3. Empacote essas partes em um plugin com um manifesto claro e skills com namespace.
4. Compartilhe através de um marketplace ou um caminho de distribuição interno.

Isso evita o modo de falha mais comum: transformar toda ideia em um plugin antes que alguém saiba se o fluxo de trabalho vale a pena ser mantido.

Se sua equipe está combinando o Claude Code com um backend de modelo alternativo, este também é o estágio onde a Novita AI pode ser útil operacionalmente. A camada de plugin e MCP permanece a mesma, enquanto o roteamento de modelo pode ser movido para a API LLM da Novita para sessões pesadas de codificação que não precisam de um modelo premium fechado em cada etapa. Essa divisão é geralmente mais simples do que redesenhar o próprio stack de extensão.

Erros Comuns na Configuração de Plugins do Claude Code

Estes são os erros que mais desperdiçam tempo:

Tratar toda extensão como um plugin

Às vezes a resposta certa é uma skill simples ou uma configuração direta de servidor MCP. Empacotar cedo demais adiciona manutenção.

Colocar arquivos no diretório errado

plugin.json vai em .claude-plugin/. Skills e hooks não.

Esquecer o namespace

Uma skill de plugin é invocada com o prefixo do plugin, não como um comando global.

Pular o recarregamento após a instalação

Se o Claude disser para executar /reload-plugins, faça isso antes de assumir que a instalação falhou.

Usar um plugin quando a necessidade real é MCP

Se o problema central é conectividade de ferramentas, foque em MCP primeiro e empacote depois.

Conclusão

A documentação de plugins do Claude Code faz mais sentido quando você para de tratar “plugin” como o único conceito de extensão. Plugins são a camada de distribuição. Skills contêm instruções reutilizáveis. Hooks automatizam eventos do ciclo de vida. MCP conecta o Claude Code a sistemas externos.

Esse enquadramento torna o resto da documentação muito mais fácil de navegar. Se seu objetivo é configuração rápida, comece com a menor unidade funcional que resolve o problema. Adicione empacotamento apenas quando a configuração valer a pena ser reutilizada.

FAQ

Os plugins do Claude Code são a mesma coisa que servidores MCP?

Não. Servidores MCP são a camada de conexão para ferramentas e serviços externos. Plugins são uma camada de empacotamento que pode incluir configuração MCP junto com skills, hooks, agents e outras extensões do Claude Code.

Como instalo um plugin do Claude Code?

De dentro do Claude Code, use o comando /plugin install com o nome do plugin e do marketplace. Se o marketplace não estiver presente, adicione-o com /plugin marketplace add ..., depois recarregue os plugins se o Claude solicitar.

Devo usar um plugin ou apenas arquivos .claude/?

Use arquivos .claude/ para iteração rápida específica de projeto. Use um plugin quando a configuração precisar ser reutilizada entre projetos, compartilhada com colegas ou distribuída através de um marketplace.

Quando devo usar MCP em vez de um plugin?

Use MCP primeiro quando seu objetivo principal for acesso externo a sistemas como GitHub, Jira, Notion, Slack ou APIs internas. Se você está comparando um guia de MCP plugin com uma página de documentação de plugin, trate o guia MCP como a referência de conexão de ferramentas e a página de documentação de plugin como a referência de empacotamento. Empacote essa configuração como um plugin depois apenas se precisar de reutilização e distribuição mais limpas.

Os plugins do Claude Code podem funcionar com backends de modelo que não são da Anthropic?

Sim. A camada de extensão e o backend do modelo são preocupações separadas. Na prática, isso significa que você pode manter a mesma configuração de plugin e MCP do Claude Code enquanto roteia a inferência através de um provedor compatível, como a Novita AI, para fluxos de trabalho de codificação suportados.

Artigos Recomendados

• Plugins do Claude Code: Como Ferramentas MCP Estendem o Claude Code com Capacidades Externas
• Regras do Claude Code: Como Escrever CLAUDE.md e Gerenciar Contexto de Codificação Agentiva
• Construa um Servidor MCP de Execução Remota de Código com Novita Sandbox e a Biblioteca mcp-use

Fontes verificadas em 31 de agosto de 2026: Visão geral de recursos do Claude Code, Documentação de plugins do Claude Code, Documentação MCP do Claude Code e Biblioteca de modelos da Novita AI.