- O Que o MCP Faz no Claude
- Adicionando Servidores MCP no Claude Code
- Configuração de Servidores MCP no Claude Desktop
- Tipos de Transporte MCP: stdio vs SSE
- Como o Claude Raciocina Sobre Ferramentas MCP
- Executando Ferramentas em uma Sandbox
- Usando a Novita LLM API para Raciocínio de Uso de Ferramentas MCP
- Problemas Comuns e Correções
- FAQ
- Artigos Recomendados
O Claude suporta nativamente o Model Context Protocol (MCP), permitindo que você conecte ferramentas externas — bancos de dados, executores de código, APIs e servidores personalizados — diretamente ao seu fluxo de trabalho. Esteja você usando o Claude Code no terminal ou o Claude Desktop na sua máquina, a configuração do MCP funciona da mesma forma a nível de protocolo, com algumas diferenças em como você registra os servidores. Este guia cobre ambos os caminhos: os comandos claude mcp add da CLI para o Claude Code e o arquivo de configuração JSON para o Claude Desktop, além de explicar como o raciocínio de uso de ferramentas e a execução em sandbox se encaixam no cenário.
O Que o MCP Faz no Claude
O MCP é um padrão aberto da Anthropic que oferece aos modelos de linguagem uma maneira uniforme de chamar ferramentas externas. Antes do MCP, cada aplicativo de IA precisava de código de integração personalizado para cada ferramenta que desejava usar. Com o MCP, qualquer servidor compatível expõe suas capacidades por meio de um protocolo padrão de descoberta e invocação, e qualquer host compatível — incluindo o Claude — pode usá-las sem trabalho de integração por ferramenta.
Em termos práticos: quando você adiciona um servidor MCP ao Claude, está informando ao host Claude onde encontrar um conjunto de ferramentas. O Claude pode então listar essas ferramentas durante uma sessão e chamá-las pelo nome quando a tarefa justificar. O servidor cuida da execução; o Claude cuida do raciocínio sobre quando e como chamar.
Três conceitos principais fundamentam o MCP:
| Conceito | O que é | Exemplo |
|---|---|---|
| Ferramenta (Tool) | Uma função chamável exposta pelo servidor | run_python, query_db, list_models |
| Recurso (Resource) | Dados somente leitura que o servidor disponibiliza como contexto | Um arquivo, uma linha de banco de dados, um conjunto de dados |
| Prompt | Modelos de instrução pré-construídos fornecidos com o servidor | Uma descrição de tarefa a nível de sistema |
Para a maioria dos desenvolvedores, as ferramentas são o que mais importa. Recursos e prompts tornam-se relevantes quando você está construindo um pipeline de agente mais estruturado.
Adicionando Servidores MCP no Claude Code
O Claude Code expõe o gerenciamento de MCP através do grupo de subcomandos claude mcp. Você pode adicionar, remover e listar servidores sem tocar em nenhum arquivo de configuração manualmente.
claude mcp add — a forma básica
claude mcp add <nome> <comando> [args...]
Por exemplo, para adicionar um servidor MCP Python local:
claude mcp add my-tools python /path/to/mcp_server.py
Isso registra um servidor chamado my-tools que executa python /path/to/mcp_server.py usando transporte stdio. O Claude Code inicia o processo quando você inicia uma sessão e o mantém ativo durante toda a duração.
Passando variáveis de ambiente
Muitos servidores MCP precisam de chaves de API ou URLs de endpoint. Use --env para passá-las no momento do registro:
claude mcp add my-tools python /path/to/mcp_server.py \
--env API_KEY=sua_chave_aqui \
--env BASE_URL=https://api.example.com
Os valores são armazenados na configuração do Claude Code e injetados no processo do servidor na inicialização. Não codifique segredos diretamente no comando do servidor.
claude mcp add json — registrando a partir de uma especificação JSON
Se você já tem uma especificação de servidor escrita em JSON (comum ao compartilhar configurações em uma equipe), pode passá-la diretamente via pipe:
echo '{
"command": "python",
"args": ["/path/to/mcp_server.py"],
"env": {
"API_KEY": "sua_chave"
}
}' | claude mcp add my-tools --json
Ou passe um arquivo:
claude mcp add my-tools --json < server-spec.json
Isso é equivalente à forma posicional, mas oferece um único artefato de configuração que você pode versionar e compartilhar.
Listando e removendo servidores
# Ver todos os servidores registrados
claude mcp list
# Remover um servidor
claude mcp remove my-tools
Escopo: projeto vs usuário
Por padrão, claude mcp add registra o servidor na sua configuração de nível de usuário, tornando-o disponível em todas as sessões do Claude Code. Para registrá-lo apenas no projeto atual (armazenado em .claude/settings.json), adicione --scope project:
claude mcp add my-tools python /path/to/mcp_server.py --scope project
Servidores com escopo de projeto são úteis quando diferentes projetos precisam de ferramentas diferentes e você deseja manter as configurações isoladas.
claude mcp serve — expondo o Claude Code como um servidor MCP
A direção também funciona ao contrário. claude mcp serve inicia o próprio Claude Code como um servidor MCP, permitindo que outro host MCP se conecte a ele e use suas ferramentas:
claude mcp serve
Isso é útil se você deseja compor as capacidades do Claude Code em um pipeline de agente maior, onde um host diferente está orquestrando as chamadas de ferramenta.
Configuração de Servidores MCP no Claude Desktop
O Claude Desktop armazena a configuração do servidor MCP em um arquivo JSON. A localização depende do seu sistema operacional:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Se o arquivo não existir, crie-o. A estrutura é assim:
{
"mcpServers": {
"my-tools": {
"command": "python",
"args": ["/path/to/mcp_server.py"],
"env": {
"API_KEY": "sua_chave_aqui"
}
}
}
}
Cada chave em mcpServers é o nome do servidor que o Claude usará para identificá-lo. Você pode registrar quantos servidores precisar — o Claude Desktop carrega todos eles na inicialização.
Após editar o arquivo, reinicie o Claude Desktop para que as alterações entrem em vigor. Você verá um ícone de martelo na área de entrada de chat quando as ferramentas MCP forem carregadas com sucesso.
Adicionando um servidor MCP remoto via SSE
Para servidores remotos que usam transporte Server-Sent Events (SSE) em vez de stdio, a estrutura de configuração é ligeiramente diferente:
{
"mcpServers": {
"remote-tools": {
"url": "https://seu-servidor-mcp.example.com/sse"
}
}
}
Alguns servidores remotos exigem autenticação. Passe um token de portador no campo de cabeçalhos se o servidor esperar por ele:
{
"mcpServers": {
"remote-tools": {
"url": "https://seu-servidor-mcp.example.com/sse",
"headers": {
"Authorization": "Bearer seu_token_aqui"
}
}
}
}
Tipos de Transporte MCP: stdio vs SSE
Os servidores MCP se comunicam com o host Claude através de um de dois mecanismos de transporte:
stdio — O servidor é executado como um subprocesso na mesma máquina. O host inicia o processo e lê/escreve mensagens JSON-RPC através da entrada/saída padrão. Este é o padrão para servidores locais e é o mais simples de configurar.
SSE (Server-Sent Events) — O servidor é executado remotamente e expõe um endpoint HTTP. O host se conecta a uma URL e recebe as respostas das ferramentas como um fluxo. Isso funciona entre máquinas e é a escolha certa para infraestrutura compartilhada de equipe ou serviços de ferramentas hospedados.
Para a maioria dos desenvolvedores individuais começando, o stdio é mais fácil — sem necessidade de rede, e o processo do servidor é gerenciado para você. O SSE se torna valioso quando você quer que uma equipe compartilhe um único servidor MCP, ou quando a própria ferramenta precisa ser executada em um ambiente de rede específico.
Como o Claude Raciocina Sobre Ferramentas MCP
Quando uma sessão é iniciada e os servidores MCP estão registrados, o Claude consulta cada servidor por suas ferramentas disponíveis. Isso produz uma lista de nomes de ferramentas e descrições em JSON Schema. O Claude não chama ferramentas especulativamente — ele só invoca uma ferramenta quando a conversa ou tarefa exige, com base no que a descrição da ferramenta diz que ela faz.
O fluxo de chamada de ferramenta funciona assim:
- O usuário envia uma mensagem ou tarefa.
- O Claude avalia se alguma ferramenta registrada pode ajudar.
- Se sim, o Claude constrói uma chamada de ferramenta com os argumentos apropriados.
- O host MCP envia a chamada para o servidor correto.
- O servidor executa e retorna um resultado.
- O Claude incorpora o resultado em seu raciocínio e continua.
Esse loop pode ocorrer várias vezes em uma única rodada — o Claude pode encadear chamadas de ferramentas, usar resultados de uma ferramenta para informar argumentos de outra e agregar resultados de vários servidores na mesma sessão.
A qualidade das descrições das ferramentas é muito importante aqui. Descrições vagas levam a invocações perdidas ou incorretas. Descrições precisas que incluem o que a ferramenta faz, o que seus argumentos significam e o que ela retorna permitem que o Claude roteie as chamadas com precisão sem precisar adivinhar.
Executando Ferramentas em uma Sandbox
Quando as ferramentas MCP executam código — scripts Python, comandos shell, operações de arquivos — executá-las na sua máquina local levanta questões sobre isolamento. Uma ferramenta com acesso ao sistema de arquivos, criação de processos ou chamadas de rede tem um alcance amplo se se comportar mal ou for induzida a um caminho inesperado.
O Novita AI 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. O agente pode escrever arquivos, executar código e chamar APIs internas dentro desse limite sem tocar na máquina host.
O servidor MCP executando dentro da sandbox expõe suas ferramentas através do transporte SSE, e o Claude se conecta a ele remotamente — então, da perspectiva do Claude, a integração é idêntica. A diferença está inteiramente no que a ferramenta está realmente executando.
Principais características do Novita Sandbox para implantações MCP:
- Inicialização rápida: instâncias são iniciadas 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 de dados entre sessões
- Política de rede configurável: controle quais serviços externos a ferramenta pode acessar
Para um guia passo a passo sobre como construir um servidor MCP apoiado por um Novita Sandbox, veja Build a Remote Code Execution MCP Server with Novita Sandbox and mcp-use Library.
Usando a Novita LLM API para Raciocínio de Uso de Ferramentas MCP
Embora os próprios modelos do Claude lidem com o uso de ferramentas nativamente, você pode querer rotear parte do raciocínio de uso de ferramentas MCP através de um modelo diferente — por questões de custo, latência ou especialização. A Novita LLM API fornece um endpoint compatível com OpenAI com acesso a modelos que suportam chamada de funções e invocação estruturada de ferramentas.
Isso se encaixa em arquiteturas MCP de duas maneiras:
1. Como o modelo de raciocínio por trás de um host MCP personalizado: Se você está construindo seu próprio host MCP (em vez de usar o Claude Code ou Claude Desktop), pode usar a Novita LLM API para alimentar a camada de modelo. O host chama a API da Novita com a lista de ferramentas e a conversa; o modelo retorna instruções de chamada de ferramenta; o host as despacha para o servidor MCP.
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 um teste rápido"}],
tools=[
{
"type": "function",
"function": {
"name": "list_models",
"description": "Lista todos os modelos disponíveis da API.",
"parameters": {"type": "object", "properties": {}},
}
}
],
tool_choice="auto",
)
2. Como o LLM dentro da própria ferramenta MCP: Uma ferramenta MCP pode usar a Novita LLM API internamente — por exemplo, uma ferramenta de sumarização, uma ferramenta de classificação ou uma ferramenta que gera código. A ferramenta aceita entradas do agente, chama a API da Novita e retorna o resultado. Isso mantém os custos de inferência do modelo separados dos custos do modelo agente principal e permite que você escolha o modelo certo para cada subtarefa.
Para um exemplo prático de construção de um servidor MCP que chama a API da Novita, veja How to Build Your First MCP Server with Novita AI.
Problemas Comuns e Correções
Servidor não aparece no Claude Desktop
A causa mais comum é um erro de sintaxe JSON no claude_desktop_config.json. Use um validador JSON antes de salvar. Até mesmo uma vírgula no final impede que o arquivo seja carregado. Reinicie o Claude Desktop após cada edição.
Comando claude mcp add não encontrado
Isso significa que o Claude Code não está instalado ou não está no seu PATH. Instale o Claude Code via npm install -g @anthropic-ai/claude-code e verifique com claude --version.
Ferramentas listadas mas nunca chamadas
O Claude só chama uma ferramenta quando acredita que ela é relevante para a tarefa atual. Se suas descrições de ferramentas forem muito vagas, o Claude não as selecionará. Adicione especificidades: o que a ferramenta faz, quando usá-la, quais são suas entradas e saídas.
Servidor sai imediatamente após a inicialização
Verifique se o comando do servidor está correto e se todas as variáveis de ambiente necessárias estão definidas. Execute o comando diretamente em um terminal para ver a saída de erro real — o Claude Code pode suprimir stderr do subprocesso em algumas configurações.
Conexão SSE recusada
Verifique se a URL do servidor é acessível a partir da máquina que executa o Claude, se o servidor está realmente ouvindo na porta esperada e se quaisquer cabeçalhos de autenticação necessários estão configurados corretamente.
Chamadas de ferramenta falham com erros de validação
Os argumentos que o Claude passa devem corresponder ao JSON Schema que a ferramenta declara. Revise a definição inputSchema da sua ferramenta — se campos obrigatórios estiverem faltando ou os tipos não corresponderem, o servidor rejeitará a chamada. O Claude constrói argumentos com base no esquema, então um esquema incompleto leva a chamadas incompletas.
FAQ
O Claude Code suporta MCP?
Sim. O Claude Code tem suporte nativo a MCP através do subcomando claude mcp. Use claude mcp add para registrar servidores, claude mcp list para ver o que está registrado e claude mcp remove para remover o registro. Execute claude mcp --help para a referência completa do comando.
Como adiciono um servidor MCP ao Claude Code?
Execute claude mcp add <nome> <comando> [args...] para um servidor stdio, ou use --json para passar uma especificação JSON. Para registro com escopo de projeto, adicione --scope project. Após adicionar, inicie uma nova sessão do Claude Code — as ferramentas estarão disponíveis imediatamente.
O que é claude mcp serve?
claude mcp serve executa o Claude Code como um servidor MCP, expondo suas capacidades através do protocolo MCP. Outro host MCP pode então se conectar ao Claude Code e usá-lo como uma fonte de ferramentas. Isso é útil ao construir sistemas multiagente onde o Claude é um componente entre vários.
Posso usar o mesmo servidor MCP tanto no Claude Code quanto no Claude Desktop?
Sim. O servidor em si não se importa qual host se conecta a ele. Para servidores stdio, tanto o Claude Code (via claude mcp add) quanto o Claude Desktop (via claude_desktop_config.json) podem iniciar o mesmo comando. Para servidores SSE, qualquer host que possa acessar a URL pode se conectar.
Como o Claude sabe qual ferramenta MCP chamar?
No início da sessão, o Claude consulta todos os servidores registrados por suas listas de ferramentas. Cada ferramenta tem um nome e uma descrição. Ao processar uma tarefa, o Claude seleciona ferramentas com base em se suas descrições correspondem ao que é necessário. Descrições bem escritas com casos de uso claros levam a uma seleção precisa de ferramentas; descrições vagas levam a chamadas perdidas ou incorretas.
Há um limite de quantos servidores MCP posso registrar?
A especificação MCP não impõe um limite rígido, e nem o Claude Code nem o Claude Desktop. Na prática, ter dezenas de servidores com centenas de ferramentas pode tornar a inicialização da sessão mais lenta (a descoberta de ferramentas é executada na inicialização) e pode adicionar ruído à seleção de ferramentas do Claude. Mantenha o conjunto de ferramentas focado no que um determinado projeto ou sessão realmente precisa.
Qual é a diferença entre transporte stdio e SSE?
Stdio executa o servidor como um subprocesso local; o host se comunica via stdin/stdout. SSE se conecta a um endpoint HTTP remoto e recebe respostas como um fluxo. Stdio é mais simples para desenvolvimento local; SSE é melhor para implantações remotas, compartilhadas ou de produção.
