Plugins do Claude Code: Como as Ferramentas MCP Estendem o Claude Code com Capacidades Externas

O Claude Code não possui um sistema de plugins tradicional com um marketplace e instalação com um clique. Ele usa o Model Context Protocol (MCP), um padrão aberto da Anthropic para anexar ferramentas externas a uma sessão do Claude Code. Os servidores MCP funcionam como plugins: eles expõem ferramentas que podem ser chamadas, o Claude decide quando usá-las e o resultado retorna para a conversa. Este guia explica o modelo de extensão; para configuração CLI e JSON copiável, 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 criadas pela 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 de plugin proprietário. Isso significa:

• Nenhum marketplace separado: as ferramentas são distribuídas como servidores MCP, não através de um registro específico da plataforma
• Nenhum bloqueio em 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 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 de acordo com a especificação MCP funciona com o Claude Code, e milhares já existem 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-os para obter suas listas de ferramentas e, em seguida, usa essas ferramentas quando a conversa as solicitar.

Três coisas compõem a interface de um servidor MCP:

Objeto	O que é	Exemplo
Ferramenta	Uma função chamá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, um fixture de teste
Prompt	Modelos de instrução pré-construídos empacotados com o servidor	Uma lista de verificação de revisão de código, um modelo de tarefa

Para a maioria dos fluxos de trabalho do Claude Code, as ferramentas são o que importa. Recursos e prompts entram em cena quando você está construindo pipelines agentivos mais estruturados.

A sequência principal do protocolo:

1. O Claude Code inicia, lê sua configuração e inicia os servidores registrados
2. Cada servidor responde a uma consulta tools/list com nomes e definições de JSON Schema
3. Durante uma sessão, o Claude usa essas definições para decidir quando e como chamar cada ferramenta
4. O Claude Code despacha a chamada, o servidor executa e retorna o resultado, o Claude incorpora o resultado e continua

O servidor lida com a execução. 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 no Claude Code. Execute uma vez; o servidor está 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 --version deve funcionar)
• Node.js 18 ou superior para servidores baseados em npm
• Python 3.10 ou superior para servidores baseados em Python

Adicionando o plugin do 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 para 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 se foi registrado:

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 iniciará 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 o 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 esquemas 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 da equipe — commit junto com o código
user	Toda sessão 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 de equipe 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 fazem

O ecossistema MCP cresceu substancialmente desde que a Anthropic publicou o protocolo. Algumas categorias com uso no mundo 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 com escopo ao sistema de arquivos — 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 pesquisa 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
Novita Sandbox MCP server	Execução isolada de Python/Node em sandboxes na nuvem
@modelcontextprotocol/server-memory	Memória persistente chave-valor entre sessões

Estes podem ser instalados 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, baseado inteiramente na descrição da ferramenta.

A lógica de roteamento em alto nível:

1. No início da sessão, o Claude consulta todos os servidores registrados e constrói um catálogo de ferramentas
2. Para cada mensagem do usuário ou etapa da tarefa, o Claude avalia se alguma descrição de ferramenta corresponde ao que é necessário
3. Se uma correspondência parecer promissora, o Claude constrói uma chamada com argumentos apropriados com base no JSON Schema da ferramenta
4. 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 críticas. 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 quais 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.

O Claude também pode encadear chamadas de ferramentas em uma única rodada: ler um arquivo para entender o contexto, pesquisar por 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 a execução de plugins em uma 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 iniciar processos tem uma superfície ampla se 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. A 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 é inteiramente onde a execução ocorre.

Características principais do Novita Sandbox para execução de ferramentas MCP:

• Inicialização rápida: as instâncias são lançadas em média em menos de ~200ms, mantendo a latência de ida e volta da ferramenta baixa
• Cobrança 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 alcançar

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 de Código Remota 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 razões de acesso a modelo — a camada de raciocínio para chamadas de ferramentas também passa por esse provedor.

A API LLM da Novita fornece um endpoint compatível com Anthropic em https://api.novita.ai/anthropic. Configure-o 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 esta configuração, as chamadas de ferramenta MCP do Claude Code continuam a funcionar 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 o 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 resultados de ferramentas anteriores acessíveis durante uma sessão complexa.
• MiniMax M2.7 — otimizado para precisão agentiva no uso de ferramentas, projetado especificamente para reduzir invocações incorretas de ferramentas e lidar com sequências de múltiplas etapas onde cada passo 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ê estiver 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 chamada de função:

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 peso aberto atue como a camada de raciocínio em um pipeline MCP personalizado, com características de custo ou latência diferentes de modelos fechados.

Modelos de peso aberto como backbone alternativo

Uma opção subestimada para fluxos de trabalho MCP intensivos no Claude Code é substituir completamente o modelo Claude padrão por uma alternativa de peso aberto capaz. Modelos como Qwen3-Coder, MiniMax M2.7 e DeepSeek V3.1 foram treinados especificamente para precisão em chamada 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 chamada de função, a uma fração do custo.

Para equipes que executam sessões agentivas de alto volume — pipelines de CI, revisão de código automatizada, 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ê estiver construindo seu próprio servidor MCP para o Claude Code, a qualidade de suas descrições de ferramentas determina se o Claude usará suas ferramentas de forma eficaz. Esta é a única coisa de maior alavancagem que você pode fazer por um servidor personalizado.

Uma descrição de ferramenta que funciona responde a três perguntas:

1. O que a ferramenta faz? — concreto, não abstrato
2. Quando ela deve ser chamada? — o cenário ou condição de gatilho
3. Quais são as entradas e saídas? — suficiente para o Claude construir argumentos corretos

Compare estas duas descrições para a mesma ferramenta search_codebase:

Ruim: "Pesquisa no 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 ao 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. O Claude será mais cuidadoso ao chamá-la sem evidências claras de que a ação é pretendida.
• Explique as formas de retorno: Se a ferramenta retorna um objeto JSON com uma estrutura específica, descreva os campos principais. O Claude usa isso para extrair a informação correta para o próximo passo.
• Mantenha os escopos estreitos: Uma ferramenta chamada "run_anything" que aceita comandos de shell arbitrários é mais difícil para o Claude raciocinar do que "run_tests" que executa o conjunto de testes do projeto. Ferramentas estreitas com descrições precisas funcionam melhor do que ferramentas amplas com descrições vagas.

Solucionando 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 o stderr do subprocesso. Execute claude mcp list — se o servidor mostrar um tempo limite 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 o Claude deve chamar a ferramenta e o que os argumentos significam.

npx trava na primeira execução

Adicione a flag -y para aceitar automaticamente o prompt de instalação: npx -y @pacote/mcp-server. Sem ela, o npx aguarda confirmação do usuário e o Claude Code vê um tempo limite 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

O 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.

Qual é 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 MCP em si está em modelcontextprotocol.io. Estas são as duas fontes a consultar para detalhes autoritativos do protocolo e 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”, 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 toda sessão, 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 — não importa 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 tornar a inicialização da sessão mais lenta (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 seu trabalho. 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 peso aberto suportam chamada de ferramenta MCP?

Sim. Modelos que implementam chamada de função no formato da API de mensagens Anthropic funcionam com a camada MCP do Claude Code independentemente do provedor. Qwen3-Coder, MiniMax M2.7 e DeepSeek V3.1 todos suportam chamada de ferramenta estruturada. O despacho de ferramentas é tratado pelo Claude Code; o modelo só precisa retornar instruções de chamada de ferramenta válidas no formato esperado.

---

Artigos Recomendados

• Regras do Claude Code: Como Escrever CLAUDE.md e Gerenciar Contexto de Codificação Agentivo
• Documentação CLI do Claude Code: Configuração, Comandos Slash e Integração com API LLM
• SDK do Claude Code: Guia Python e TypeScript
• Comando Claude MCP Add: Como Instalar Servidores MCP no Claude Code
• Claude MCP: Como Configurar Servidores MCP no Claude Code e Claude Desktop
• Construa um Servidor MCP de Execução de Código Remota com Novita Sandbox e a Biblioteca mcp-use