- O que "plugins do Claude Code" realmente significa
- Como os servidores MCP funcionam como plugins
- Instalando seu primeiro plugin com claude mcp add
- Escopos: local, projeto e usuário
- Plugins MCP populares e o que eles fazem
- Como o Claude roteia chamadas de ferramentas em tempo de execução
- Executando plugins em um sandbox
- Usando a API LLM da Novita para raciocínio de uso de ferramentas
- Escrevendo descrições de ferramentas que funcionam
- Solução de problemas comuns de plugins
- FAQ
- Artigos Recomendados
O Claude Code não possui um sistema de plugins tradicional com marketplace e instalação com um clique. Ele utiliza o Model Context Protocol (MCP), um padrão aberto da Anthropic para conectar ferramentas externas a uma sessão do Claude Code. Os servidores MCP funcionam como plugins: eles expõem ferramentas que podem ser chamadas, Claude decide quando usá-las e o resultado retorna para a conversa. Este guia explica o modelo de extensão; para configuração em CLI e JSON, use o guia de configuração MCP do Claude.
O que “plugins do Claude Code” realmente significa
Quando desenvolvedores pesquisam por “plugins do Claude Code”, geralmente querem uma de três coisas: uma forma de dar ao Claude Code acesso a um serviço externo (GitHub, um banco de dados, um navegador web), uma forma de instalar extensões de ferramentas da comunidade, ou documentação sobre como o mecanismo de extensão funciona.
Todas as três levam ao MCP. A Anthropic projetou o Claude Code em torno do Model Context Protocol em vez de um formato proprietário de plugins. Isso significa:
- Sem marketplace separado: ferramentas são distribuídas como servidores MCP, não através de um registro específico da plataforma
- Sem bloqueio a nível de API: qualquer desenvolvedor pode construir um servidor e compartilhá-lo
- Mesma superfície de integração: Claude Code, Claude Desktop e outros hosts do Claude usam o mesmo protocolo
O efeito prático é que o catálogo de plugins do Claude Code é o ecossistema MCP — qualquer servidor construído para o padrão MCP funciona com Claude Code, e já existem milhares para bancos de dados, APIs, navegadores, executores de código, sistemas de arquivos e muito mais.
Não existe um comando claude plugin install. O equivalente é claude mcp add.
Como os servidores MCP funcionam como plugins
Cada servidor MCP é um processo que expõe um conjunto de ferramentas através do protocolo MCP. O Claude Code inicia ou conecta-se a servidores registrados quando você inicia uma sessão, consulta suas listas de ferramentas e, em seguida, usa essas ferramentas quando a conversa exigir.
Três coisas compõem a interface de um servidor MCP:
| Objeto | O que é | Exemplo |
|---|---|---|
| Ferramenta | Uma função invocável com entradas e saídas definidas | run_python, search_docs, create_issue |
| Recurso | Dados somente leitura que o servidor expõe como contexto | Conteúdo de um arquivo, uma linha de banco de dados, uma fixture de teste |
| Prompt | Modelos de instrução pré-construídos agrupados com o servidor | Uma lista de verificação de revisão de código, um modelo de tarefa |
Para a maioria dos workflows do Claude Code, as ferramentas são o que importa. Recursos e prompts entram em jogo quando você está construindo pipelines agentivos mais estruturados.
A sequência principal do protocolo:
- O Claude Code inicia, lê sua configuração e inicia os servidores registrados
- Cada servidor responde a uma consulta
tools/listcom nomes e definições de JSON Schema - Durante uma sessão, Claude usa essas definições para decidir quando e como chamar cada ferramenta
- O Claude Code despacha a chamada, o servidor executa e retorna o resultado, Claude incorpora o resultado e continua
O servidor lida com a execução. Claude lida com o raciocínio sobre quando a execução é necessária.
Instalando seu primeiro plugin com claude mcp add
claude mcp add é o comando que registra um servidor MCP com o Claude Code. Execute uma vez; o servidor fica disponível em todas as sessões subsequentes.
# Forma básica para servidores stdio
claude mcp add <nome-do-servidor> -- <comando> [args...]
# Forma básica para servidores HTTP
claude mcp add --transport http <nome-do-servidor> <url>
Pré-requisitos antes de executar qualquer comando claude mcp add:
- Claude Code instalado e no seu PATH (
claude --versiondeve funcionar) - Node.js 18 ou superior para servidores baseados em npm
- Python 3.10 ou superior para servidores baseados em Python
Adicionando o plugin de navegador Playwright
O servidor MCP Playwright dá ao Claude um navegador real — ele pode navegar por URLs, clicar em elementos, extrair texto e retornar capturas de tela. Este é um dos primeiros plugins mais úteis de adicionar porque não requer chave de API e demonstra imediatamente o que o protocolo pode fazer.
claude mcp add playwright -- npx -y @playwright/mcp@latest
Verifique o registro:
claude mcp list
Em seguida, abra uma sessão:
Use o playwright para abrir https://example.com e me diga o título da página e o cabeçalho principal
O Claude lançará um navegador, navegará até a URL, lerá o DOM e retornará a resposta — sem necessidade de scripts da sua parte.
Adicionando um plugin de banco de dados
O servidor MCP SQLite oficial permite que Claude consulte e inspecione um banco de dados SQLite local diretamente da conversa:
claude mcp add sqlite -- uvx mcp-server-sqlite --db-path /caminho/para/seu/banco.db
Depois disso, você pode pedir ao Claude para escrever consultas, explicar o esquema ou explorar dados diretamente, sem copiar e colar definições de esquema em cada prompt.
Passando variáveis de ambiente
A maioria dos servidores com suporte a API precisa de chaves. Use --env para passá-las no momento do registro sem incorporá-las no comando:
claude mcp add linear -- npx -y @linear/mcp-server \
--env LINEAR_API_KEY=sua_chave_aqui
Os valores são armazenados na configuração do Claude Code e injetados no processo do servidor na inicialização.
Escopos: local, projeto e usuário
Por padrão, claude mcp add registra um servidor no escopo local — ele fica ativo apenas quando o Claude Code é iniciado a partir do diretório atual. Três opções de escopo oferecem diferentes modelos de compartilhamento:
| Escopo | Ativo em | Arquivo de configuração | Quando usar |
|---|---|---|---|
local (padrão) |
Apenas no diretório atual | ~/.claude.json |
Servidor de desenvolvimento pessoal para um projeto |
project |
Qualquer sessão dentro deste repositório | .mcp.json na raiz do projeto |
Ferramenta de equipe — commit junto com o código |
user |
Todas as sessões do Claude Code | ~/.claude.json no escopo do usuário |
Ferramentas globais que você sempre quer disponíveis |
Adicione --scope project para commitar a definição do servidor com seu repositório:
claude mcp add sqlite --scope project -- uvx mcp-server-sqlite --db-path ./dev.db
Isso cria .mcp.json na raiz do projeto com a definição do servidor. Colegas que executam o Claude Code no mesmo repositório obtêm a mesma ferramenta disponível automaticamente — sem configuração por desenvolvedor além de ter os pré-requisitos instalados.
Para ferramentas com escopo de usuário que fazem sentido em todos os lugares:
claude mcp add playwright --scope user -- npx -y @playwright/mcp@latest
Plugins MCP populares e o que eles fazem
O ecossistema MCP cresceu substancialmente desde que a Anthropic publicou o protocolo. Algumas categorias com uso real:
Ferramentas de desenvolvimento
| Servidor | O que adiciona |
|---|---|
@playwright/mcp |
Automação de navegador — navegar, clicar, extrair, capturar tela |
@modelcontextprotocol/server-git |
Ler commits, diffs, branches, blame de repositórios locais |
@modelcontextprotocol/server-filesystem |
Acesso ao sistema de arquivos com escopo — ler/escrever arquivos em caminhos definidos |
mcp-server-sqlite |
Consultar e inspecionar bancos de dados SQLite |
Serviços e APIs
| Servidor | O que adiciona |
|---|---|
@linear/mcp-server |
Criar, ler e atualizar issues do Linear |
@sentry/mcp-server |
Consultar erros e traces do Sentry |
@modelcontextprotocol/server-github |
Repositórios, issues, PRs e busca de código do GitHub |
@notionhq/notion-mcp-server |
Ler e escrever páginas e bancos de dados do Notion |
IA e execução de código
| Servidor | O que adiciona |
|---|---|
| Servidor MCP Novita Sandbox | Execução isolada de Python/Node em sandboxes na nuvem |
@modelcontextprotocol/server-memory |
Memória chave-valor persistente entre sessões |
Estes são instaláveis através de claude mcp add com npx para pacotes baseados em npm ou uvx/pip para pacotes Python.
Como o Claude roteia chamadas de ferramentas em tempo de execução
O Claude não chama ferramentas aleatoriamente ou exaustivamente. Ele raciocina sobre qual ferramenta (se houver) é apropriada para cada etapa de uma tarefa, com base inteiramente na descrição da ferramenta.
A lógica de roteamento em alto nível:
- No início da sessão, Claude consulta todos os servidores registrados e constrói um catálogo de ferramentas
- Para cada mensagem do usuário ou etapa da tarefa, Claude avalia se alguma descrição de ferramenta corresponde ao que é necessário
- Se uma correspondência parecer promissora, Claude constrói uma chamada com argumentos apropriados com base no JSON Schema da ferramenta
- O Claude Code despacha a chamada, aguarda o resultado e o incorpora antes da próxima etapa
Uma consequência: as descrições das ferramentas são essenciais. Uma descrição vaga como "ferramenta útil" resultará na ferramenta nunca ser chamada. Uma descrição que diz exatamente o que a ferramenta faz, quando chamá-la e como são suas entradas e saídas leva a um uso preciso e confiável.
Se você construir seu próprio servidor MCP e as ferramentas não estiverem sendo chamadas apesar de estarem registradas, a descrição é quase sempre o problema — não a implementação.
Claude também pode encadear chamadas de ferramentas em um único turno: ler um arquivo para entender o contexto, pesquisar uma dependência, executar um teste, verificar a saída e sugerir uma correção — cada etapa usando uma ferramenta diferente de um servidor potencialmente diferente.
Executando plugins em um sandbox
Quando plugins executam código — scripts Python, comandos de shell, automação de navegador — executá-los em sua máquina local traz riscos. Uma ferramenta com acesso ao sistema de arquivos ou capacidade de criar processos tem uma superfície ampla se ela se comportar mal ou receber um prompt malformado.
O Novita Agent Sandbox resolve isso fornecendo ambientes de nuvem isolados para execução de ferramentas. Em vez de executar seu servidor MCP localmente, você o implanta dentro de uma instância de sandbox. O sandbox tem seu próprio sistema de arquivos, escopo de rede e limites de recursos. A execução da ferramenta acontece dentro desse limite sem tocar na máquina host.
Da perspectiva do Claude, a integração é idêntica — a lista de ferramentas parece a mesma e as chamadas funcionam da mesma forma. A diferença está inteiramente em onde a execução ocorre.
Características principais do Novita Sandbox para execução de ferramentas MCP:
- Inicialização rápida: instâncias são lançadas em média em menos de ~200ms, mantendo a latência de ida e volta da ferramenta baixa
- Faturamento por segundo: você paga apenas pelo tempo de execução ativo, não pela reserva ociosa
- Sistema de arquivos isolado: cada instância de sandbox tem um espaço de trabalho separado, evitando vazamento entre sessões
- Escopo de rede configurável: controle quais serviços externos a ferramenta pode acessar
Para usar o SDK do Novita Sandbox dentro de um manipulador de ferramenta MCP:
pip install novita-sandbox
from novita_sandbox.code_interpreter import Sandbox
def execute_code(code: str, api_key: str) -> dict:
sandbox = Sandbox.create(
template="code-interpreter-v1",
api_key=api_key,
domain="sandbox.novita.ai",
timeout=300,
)
result = sandbox.run_code(code, language="python")
sandbox.kill()
return {
"output": result.logs,
"error": result.error,
}
O template code-interpreter-v1 vem com pandas, numpy, matplotlib e outros pacotes comuns pré-instalados. Para um passo a passo completo, veja Construa um Servidor MCP de Execução Remota de Código com Novita Sandbox e a Biblioteca mcp-use.
Usando a API LLM da Novita para raciocínio de uso de ferramentas
O Claude Code lida com o raciocínio de uso de ferramentas usando o modelo configurado como seu backend. Se você estiver roteando o Claude Code através de um provedor alternativo — por custo, latência ou acesso ao modelo — a camada de raciocínio para chamadas de ferramentas também será roteada através desse provedor.
A API LLM da Novita fornece um endpoint compatível com Anthropic em https://api.novita.ai/anthropic. Configure uma vez com três variáveis de ambiente:
export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_AUTH_TOKEN="sua-chave-api-novita"
export ANTHROPIC_MODEL="qwen/qwen3-coder-480b-a35b-instruct"
export ANTHROPIC_SMALL_FAST_MODEL="deepseek/deepseek-v4-flash"
Com essa configuração, as chamadas de ferramentas MCP do Claude Code continuam funcionando exatamente como antes. O roteamento afeta qual modelo faz o raciocínio — não o mecanismo de despacho de ferramentas, que permanece na camada do Claude Code.
Escolhas de modelo para sessões com muitas ferramentas:
- Qwen3-Coder 480B — adequado para tarefas de longo horizonte onde Claude precisa ler muitos arquivos, planejar uma sequência de várias etapas e chamar ferramentas em cada estágio. Seu manuseio de contexto longo mantém os resultados anteriores das ferramentas acessíveis durante uma sessão complexa.
- MiniMax M2.7 — otimizado para precisão no uso de ferramentas agentivas, projetado especificamente para reduzir invocações incorretas de ferramentas e lidar com sequências de múltiplas etapas onde cada uma se baseia no resultado anterior.
- DeepSeek V4 Flash — rápido e barato, uma boa escolha para
ANTHROPIC_SMALL_FAST_MODEL. O Claude Code usa este slot para sumarização de sessão e compressão de contexto, nenhum dos quais requer raciocínio profundo.
Se você está construindo seu próprio host MCP (em vez de usar o Claude Code), a API LLM da Novita também fornece um endpoint compatível com OpenAI em https://api.novita.ai/v3/openai para modelos que suportam function calling:
import openai
client = openai.OpenAI(
base_url="https://api.novita.ai/v3/openai",
api_key="sua-chave-api-novita",
)
response = client.chat.completions.create(
model="meta-llama/llama-3.3-70b-instruct",
messages=[{"role": "user", "content": "Liste as ferramentas disponíveis e execute uma verificação rápida"}],
tools=[
{
"type": "function",
"function": {
"name": "list_files",
"description": "Lista arquivos no diretório de trabalho atual.",
"parameters": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Caminho do diretório a ser listado."
}
},
"required": ["path"]
}
}
}
],
tool_choice="auto",
)
Isso é particularmente útil para cenários onde você deseja que um modelo de pesos abertos atue como a camada de raciocínio em um pipeline MCP personalizado, com características de custo ou latência diferentes dos modelos fechados.
Modelos de pesos abertos como backbone alternativo
Uma opção subestimada para workflows MCP intensivos no Claude Code é substituir completamente o modelo Claude padrão por uma alternativa capaz de pesos abertos. Modelos como Qwen3-Coder, MiniMax M2.7 e DeepSeek V3.1 foram treinados especificamente para precisão em chamadas de ferramentas e raciocínio de múltiplas etapas — em alguns benchmarks, esses modelos igualam ou superam modelos de código fechado em tarefas de function calling, a uma fração do custo.
Para equipes que executam sessões agentivas de alto volume — pipelines de CI, revisão automatizada de código, refatoração em lote — a diferença de custo importa. A Novita AI fornece acesso a esses modelos através do mesmo endpoint compatível com Anthropic, então a mudança é uma alteração de configuração, não uma reescrita de código.
Escrevendo descrições de ferramentas que funcionam
Se você está construindo seu próprio servidor MCP para o Claude Code, a qualidade das descrições das suas ferramentas determina se Claude usa suas ferramentas de forma eficaz. Esta é a única coisa de maior alavancagem que você pode fazer para um servidor personalizado.
Uma descrição de ferramenta que funciona responde a três perguntas:
- O que a ferramenta faz? — concreto, não abstrato
- Quando ela deve ser chamada? — o cenário ou condição de gatilho
- Quais são as entradas e saídas? — o suficiente para Claude construir argumentos corretos
Compare estas duas descrições para a mesma ferramenta search_codebase:
Ruim: "Pesquisa o código-fonte."
Eficaz: "Pesquisa arquivos fonte no repositório atual por um símbolo, string ou padrão regex. Chame esta ferramenta quando precisar encontrar onde uma função é definida, localizar todos os usos de uma variável ou identificar quais arquivos referenciam um módulo específico. Retorna uma lista de caminhos de arquivo com linhas correspondentes e números de linha."
A segunda descrição diz a Claude quando chamar a ferramenta (não apenas o que ela faz), o que produz invocações muito mais precisas e oportunas.
Algumas práticas adicionais:
- Marque ferramentas mutantes claramente: Se uma ferramenta escreve em um banco de dados ou implanta código, diga isso explicitamente. Claude será mais cuidadoso ao chamá-la sem evidências claras de que a ação é intencional.
- Explique as formas de retorno: Se a ferramenta retorna um objeto JSON com uma estrutura específica, descreva os campos principais. Claude usa isso para extrair a informação correta para o próximo passo.
- Mantenha escopos estreitos: Uma ferramenta chamada
"executar_qualquer_coisa"que aceita comandos shell arbitrários é mais difícil para Claude raciocinar do que"executar_testes"que executa o conjunto de testes do projeto. Ferramentas estreitas com descrições precisas funcionam melhor do que ferramentas amplas com descrições vagas.
Solução de problemas comuns de plugins
Ferramenta não aparece após claude mcp add
Verifique se o comando do servidor é executado sem erros em um terminal novo. O Claude Code pode suprimir stderr de subprocessos. Execute claude mcp list — se o servidor mostrar um timeout ou erro, o próprio comando está falhando, não a configuração.
Ferramentas registradas, mas nunca chamadas
As descrições das ferramentas são muito vagas. Reescreva-as para especificar quando Claude deve chamar a ferramenta e o que os argumentos significam.
npx trava na primeira execução
Adicione o sinalizador -y para aceitar automaticamente o prompt de instalação: npx -y @pacote/mcp-server. Sem ele, npx aguarda confirmação do usuário e o Claude Code vê um timeout de conexão.
Servidor não ativo em um novo projeto
Você registrou no escopo local e iniciou o Claude Code de um diretório diferente. Re-adicione com --scope user para um servidor global ou execute o comando add a partir da raiz correta do projeto.
Chamadas de ferramenta falham com erros de validação de esquema
Claude constrói argumentos com base no JSON Schema da ferramenta. Se campos obrigatórios estiverem faltando no esquema ou os tipos não corresponderem, o servidor rejeita a chamada. Revise sua definição de inputSchema — esquemas incompletos levam a argumentos de chamada incompletos.
Comando claude mcp add não encontrado
Instale o Claude Code: npm install -g @anthropic-ai/claude-code, depois verifique com claude --version.
FAQ
O Claude Code tem um marketplace de plugins?
Não no sentido tradicional. O Claude Code usa o protocolo MCP em vez de um marketplace específico da plataforma. Servidores MCP construídos pela comunidade são publicados no npm, PyPI e GitHub. Alguns agregadores mantêm listas curadas, mas não há um marketplace oficial do Claude Code para navegar.
O que é a documentação de plugins do Claude Code?
A documentação oficial da Anthropic para a integração MCP do Claude Code está em docs.anthropic.com/claude-code. A especificação do MCP em si está em modelcontextprotocol.io. Estas são as duas fontes a serem consultadas para detalhes autoritativos do protocolo e da implementação.
Como um servidor MCP é diferente de um plugin do Claude Code?
Os termos se referem à mesma coisa no contexto do Claude Code. Quando desenvolvedores dizem “plugin do Claude Code”, eles geralmente significam um servidor MCP conectado ao Claude Code. A palavra “plugin” não é a terminologia oficial da Anthropic, mas o conceito mapeia diretamente: instale uma vez, use em todas as sessões, estende as capacidades do Claude com novas ferramentas.
Posso usar o mesmo servidor MCP no Claude Desktop e no Claude Code?
Sim. O servidor é agnóstico em relação ao protocolo — ele não se importa com qual host se conecta. Para servidores stdio, tanto o Claude Code (via claude mcp add) quanto o Claude Desktop (via arquivo de configuração JSON) podem iniciar o mesmo comando. Para servidores HTTP, qualquer host que possa alcançar a URL pode se conectar.
Quantos servidores MCP posso registrar?
O protocolo MCP e o Claude Code não impõem um limite rígido. Na prática, ter muitos servidores com centenas de ferramentas pode retardar a inicialização da sessão (a descoberta de ferramentas é executada na inicialização) e adicionar ruído à seleção de ferramentas do Claude. Mantenha o conjunto ativo focado no que uma determinada sessão realmente precisa.
Existem riscos de segurança ao adicionar plugins MCP?
Sim. Servidores MCP são executados como processos com as permissões necessárias para fazer seus trabalhos. Um servidor com acesso ao sistema de arquivos pode ler ou escrever arquivos; um com execução de shell pode executar comandos arbitrários. Adicione apenas servidores em que você confia. Para ambientes de produção ou compartilhados, considere executar servidores em ambientes isolados — veja a seção de sandbox acima.
Modelos de pesos abertos suportam chamadas de ferramentas MCP?
Sim. Modelos que implementam function calling no formato da API de mensagens da Anthropic funcionam com a camada MCP do Claude Code, independentemente do provedor. Qwen3-Coder, MiniMax M2.7 e DeepSeek V3.1 todos suportam chamadas de ferramentas estruturadas. O despacho de ferramentas é tratado pelo Claude Code; o modelo só precisa retornar instruções de chamada de ferramenta válidas no formato esperado.
