Como Usar o Código Claude MCP com Segurança

Como Usar o Código Claude MCP com Segurança

18 de maio de 2026
Visualizações 123
claude-code mcp mcp-server security oauth scope ai-agent developer-tools

Oi, eu sou a Lena. MCP não é mais um conceito novo, mas na prática ligar um servidor dentro do Claude Code sem encontrar problemas é mais complexo do que a maioria das pessoas espera.

Tenho usado o Claude Code com vários servidores MCP para o meu desenvolvimento diário nos últimos meses — de tudo, desde GitHub até Sentry e ferramentas internas personalizadas de consulta a banco de dados. Honestamente, a própria configuração não é difícil — a parte difícil é descobrir em quem confiar, onde olhar quando o OAuth falha e como o escopo realmente funciona. Este artigo é uma coleção condensada dos problemas que encontrei e dos detalhes oficiais que rastreei, escrito para desenvolvedores que já estão usando Claude Code e estão prontos para conectar servidores MCP.

Pré-requisitos Antes de Conectar Servidores MCP

Versão do Claude Code e suporte da plataforma

Comece verificando sua versão. O comportamento relacionado ao OAuth só se estabilizou após a v2.1.64 — foi quando o suporte ao authServerMetadataUrl foi introduzido. Versões antigas gerarão erros ao autenticar com servidores remotos. Há também uma peculiaridade conhecida no Windows: claude mcp add-json ocasionalmente retorna "Entrada inválida" ao adicionar servidores HTTP. A documentação oficial do MCP recomenda recorrer ao formato claude mcp add --transport http se você encontrar esse problema.

O que o MCP realmente pode fazer dentro do Claude Code

O MCP transforma o Claude Code de uma ferramenta que só pode ler e escrever arquivos locais e executar comandos bash em um agente que pode interagir diretamente com sistemas externos — puxando tickets do Jira, criando PRs no GitHub, consultando erros de produção no Sentry, e por aí vai. Mas aqui está um detalhe que frequentemente é ignorado: os servidores MCP são completamente isolados uns dos outros. Não há passagem de dados — cada camada é independente.

Ferramentas, recursos e prompts

De acordo com a especificação MCP, um servidor pode expor três tipos de capacidades: ferramentas (ações executáveis), recursos (fontes de dados legíveis) e prompts (modelos de interação predefinidos). O painel /mcp exibe a contagem de ferramentas para cada servidor conectado e sinaliza qualquer servidor que declare a capacidade de ferramentas, mas que na prática não exponha nenhuma ferramenta.

Passo a Passo: Adicionando Seu Primeiro Servidor MCP

Adicionando um servidor via CLI

O Claude Code suporta três tipos de transporte: HTTP (recomendado para serviços remotos), SSE (obsoleto — evite se possível) e stdio (processos locais).

Bash
# Remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Local stdio server
claude mcp add --transport stdio --env API_KEY=your_key myserver \
  -- npx -y my-mcp-server

Aqui está o detalhe que atrapalha as pessoas: todas as opções devem vir antes do nome do servidor. O -- duplo traço separa as bandeiras do Claude dos argumentos passados para o processo do servidor MCP. Se errar a ordem, o comando falha silenciosamente. Já fui mordido por isso mais de uma vez.

Adicionando via .mcp.json para compartilhamento de equipe

Use --scope project para escrever a configuração em um arquivo .mcp.json que você possa comprometer no controle de versões. Nunca coloque tokens reais neste arquivo — use referências de variáveis de ambiente em vez disso. Configurações com escopo local sobrescrevem configurações com escopo de projeto para servidores com mesmo nome, o que mantém as credenciais privadas.

Verificando que o servidor está conectado

Execute /mcp dentro do Claude Code para verificar o status e a contagem de ferramentas. Servidores HTTP/SSE tentam automaticamente conexões iniciais até três vezes a partir da v2.1.121, mas erros de autenticação e 404s não são tentados novamente — esses requerem uma alteração de configuração.

Aprovando ferramentas no primeiro uso

Na primeira vez que você invocar uma ferramenta de um novo servidor, o Claude Code solicitará permissão. Isso é verificação de confiança por design. A documentação de segurança Claude Code afirma explicitamente que novos servidores MCP exigem confirmação do usuário. Você pode aprovar uma vez ou escolher "Sempre permitir" para adicioná-la à sua lista de permissões.

Autenticação e Fluxo OAuth

Servidores que exigem tokens OAuth

A maioria dos servidores remotos — GitHub, Slack, Notion e serviços similares — requer OAuth. Claude Code possui suporte embutido para OAuth 2.1, e o fluxo é em grande parte automático: o servidor retorna um 401, Claude Code descobre os metadados OAuth (primeiro verificando os Metadados de Recursos Protegidos do RFC 9728, depois retornando ao RFC 8414), registra-se automaticamente como cliente se o Registro Dinâmico de Cliente for suportado, abre um navegador para autorização e recupera o token.

Quando um servidor não suporta Registro Dinâmico de Clientes, você verá um erro de "Servidor de autenticação incompatível". Nesse caso, registre um app OAuth pelo portal de desenvolvedores do servidor, pegue o ID do cliente e o segredo, e adicione o servidor usando --client-id e --client-secret. Alguns servidores também exigem uma porta fixa de retorno de chamada — use --callback-port para corresponder ao URI de redirecionamento que você registrou.

Onde as credenciais são armazenadas e como girá-las

Os tokens são armazenados no armazenamento seguro de credenciais do seu sistema — chaveiro do macOS ou um arquivo de credenciais criptografado em outras plataformas. Eles nunca são armazenados em arquivos de configuração em texto simples. Para rodar credenciais, abra /mcp e reautentique para o servidor relevante. Em ambientes SSH sem navegador, o Claude Code exibe um prompt "Cole código aqui" para que você possa completar a autorização em outra máquina e colar o resultado de volta.

Evitando tokens vazados em configurações compartilhadas

Vou ser direto aqui — já vi mais de uma equipe enviar configurações com tokens codificados diretamente para repositórios públicos. Sempre use referências ${ENV_VAR}** para credenciais.** Em ambientes empresariais, administradores podem implantar um arquivo managed-mcp.json com políticas de lista de permissos e negações para controlar quais servidores podem ser usados.

! [imagem] (https://cdn.10b.ai/1778226928648-2.png)

Limites de Segurança a Verificar Antes de Confiar em um Servidor

O que um servidor MCP pode ler na sua máquina

Um servidor do tipo stdio roda com as permissões do seu usuário atual, algo que muitos desenvolvedores não pensam o suficiente. Em teoria, ele pode ler seu .env, chaves SSH e credenciais AWS — tudo o que sua conta de usuário pode acessar. O Claude Code tem salvaguardas — as operações de escrita são restritas ao diretório de trabalho, e as requisições de rede exigem aprovação. O blog Anthropic Security Engineering detalha o mecanismo de sandboxing, que inclui o trabalho conjunto de isolamento do sistema de arquivos e da rede. Os dados internos mostram que o sandboxing reduz os pedidos de permissão em 84%, o que é significativo para o fluxo de trabalho diário.

O que ela pode executar ou escrever

Ferramentas MCP podem incluir capacidades arbitrárias de execução. Uma ferramenta "run SQL" conectada a um banco de dados de produção realmente executará consultas contra dados de produção. Isso não é hipotético — já vi configurações onde uma única ferramenta mal configurada teve acesso de escrita a um banco de dados de clientes ao vivo. Antes de conectar qualquer servidor, você precisa entender exatamente quais ferramentas ela expõe e o que cada uma realmente pode fazer. Mantenha tudo que você não tiver certeza no modo de pergunta, em vez de aprovar automaticamente.

Revisando a fonte e a manutenção antes da aprovação

Antes de confiar em um servidor, normalmente faço três coisas: revisar o código-fonte (verificar o arquivo de entrada principal no GitHub para confirmar o que ele realmente faz), avaliar o status de manutenção (um pacote publicado há 3 dias versus um mantido por 2 anos — perfis de risco completamente diferentes) e verificar as declarações de permissão (de acordo com a especificação de autorização MCP, os servidores devem declarar seus escopos necessários — fique atento a qualquer coisa que ultrapasse limites razoáveis).

Problemas Comuns e Como Corrigi-los

Servidor não aparecendo após ser adicionado

A causa mais comum: ​escopo errado​. Um servidor adicionado com --scope local no diretório do projeto A não ficará visível quando você mudar para o projeto B. Use claude mcp list para confirmar o escopo e mude para --scope user se precisar que ele esteja disponível em todos os lugares. Também vale notar: workspace é um nome reservado — usá-lo fará com que o servidor seja ignorado com um aviso.

Chamadas de ferramenta falhando silenciosamente

Primeiro, verifique se a saída excede o limite padrão de 10.000 tokens. O Claude Code mostra um aviso quando isso acontece, mas é fácil de perder. Configure MAX_MCP_OUTPUT_TOKENS=50000 para aumentar o teto. Outra possibilidade é uma desconexão — servidores HTTP/SSE reconectam automaticamente com backoff exponencial (até 5 tentativas), mas servidores stdio não se reconectam automaticamente.

Conflitos de escopo entre configurações local e do projeto

Quando um servidor com o mesmo nome existe tanto no escopo local quanto no do projeto, ​o local sobrescreve o projeto​. Isso é intencional, mas se você não souber disso, vai se perguntar por que suas alterações em .mcp.json não estão surtindo efeito. Use claude mcp get <name> para ver qual configuração está realmente ativa.

Solicitações de permissão se repetindo a cada sessão

Se você não selecionou "Sempre permitir", a aprovação não será mantida. Use /permissions para gerenciar sua lista de permissões permanente. O repositório Claude Code no GitHub possui documentação sobre hooks PreToolUse, que permitem uma lógica de aprovação automatizada mais detalhada.

Onde a Conexão Deixa de Ser Suficiente

MCP fornece ferramentas, mas não preserva o que funcionou

Esta é a limitação que sinto mais intensamente no uso diário. O MCP resolve o problema de "conexão" — ele não resolve o problema de "memória". Você pode passar 20 minutos hoje fazendo um fluxo de trabalho de consulta a banco de dados mais geração de relatório funcionar perfeitamente, apenas para descobrir que a nova sessão de amanhã perdeu todo esse contexto. Você precisará reexplicar quais tabelas consultar, em qual formato produzir a saída e quais casos especiais lidar. O protocolo MCP não inclui nenhum mecanismo de persistência de sessão. Cada conexão é sem estado. Isso não é um bug — é uma fronteira de design.

Por que os times ainda repetem correções entre sessões e máquinas

O Desenvolvedor A descobre a maneira correta de usar um servidor específico, resolve um caso especial e faz tudo funcionar perfeitamente. Mas esse conhecimento conquistado com esforço não tem onde viver. O Desenvolvedor B entra no projeto uma semana depois e enfrenta exatamente os mesmos problemas, gastando o mesmo tempo depurando os mesmos problemas. .mcp.json compartilha configuração — não compartilha "como realmente usar" ou "o que quebrou da última vez e como consertamos". Arquivos CLAUDE.md podem mitigar isso parcialmente, mas são estáticos e mantidos manualmente. O MCP faz muito bem o que faz, mas para fluxos de trabalho complexos, você acabará enfrentando o problema do contexto perdido e do conhecimento tribal repetido.

FAQ

MCP é a mesma coisa que um plugin?

Não exatamente. O MCP é um padrão de protocolo aberto que define como aplicativos de IA se comunicam com ferramentas externas. Plugins são um conceito de nível superior no Claude Code que podem incluir configurações de servidor MCP juntamente com outros tipos de extensões. Página de anúncio da Anthropic tem o post original de lançamento do MCP.

Preciso de uma chave de API para usar os servidores MCP?

Depende do servidor. Servidores locais stdio normalmente não requerem autenticação. Servidores HTTP remotos geralmente precisam de credenciais — seja um token Bearer (passado via --header) ou OAuth (manipulado automaticamente).

Os colegas de equipe podem ver meus servidores MCP?

Apenas configurações --scope project são escritas em .mcp.json e visíveis para seu time. Tanto os escopos locais (o padrão) quanto os de usuário são privados.

Qual é a diferença entre escopo local, de projeto e de usuário?

local (padrão): disponível apenas para você no diretório do projeto atual. ​projeto​: gravado em .mcp.json na raiz do projeto, compartilhado com toda a equipe via controle de versão. ​usuário​: disponível para você em todos os projetos na sua máquina. Observe que em versões mais antigas, local era chamado de "projeto" e usuário era chamado de "global" — a nomenclatura foi atualizada desde então, então não se confunda com postagens de blogs ou guias antigos que usam a terminologia antiga.

Por que o Claude Code continua pedindo permissão para a mesma ferramenta?

Novas sessões não herdam aprovações temporárias por padrão. Use "Sempre permitir" ou /permissions para adicionar ferramentas à sua lista de permissões permanente. Em configurações corporativas, regras de negação em managed-settings.json substituem suas regras de permissão local, o que também pode causar rejeições repetidas.

Postagens Anteriores:

Artigos relacionados

Como Usar o Código Claude MCP com Segurança - EvoMap Blog