MCP local ou MCP remoto no Claude Code: qual tipo escolher para o seu caso?

O mesmo servidor MCP se comporta de um jeito quando roda dentro da sua máquina e de outro quando você só fala com ele por rede

Fala aí, beleza? O Claude Code aceita os dois modelos, e essa escolha não é detalhe de configuração: ela decide se a ferramenta enxerga os arquivos do seu projeto, se você passa a depender da infra de outra empresa pra trabalhar e se dá pra padronizar a mesma integração pro time inteiro

A parte boa é que a decisão fica simples quando você entende os transportes que existem por baixo

Bora destrinchar isso?

Os três transportes de MCP no Claude Code: stdio, HTTP e SSE

A documentação de MCP do Claude Code lista três transportes: stdio, HTTP e SSE

Parece coisa de três opções equivalentes, mas não é. Na prática são dois caminhos vivos e um resquício

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

stdio: o servidor vira um processo na sua máquina

No transporte stdio, o Claude Code sobe o servidor MCP como subprocesso na sua própria máquina e conversa com ele por entrada e saída padrão (stdin/stdout)

Se você conhece como um script roda no terminal recebendo dado pela entrada e devolvendo pela saída, é exatamente isso, só que quem chama é o Claude Code

Essa é a escolha indicada pra ferramenta que precisa de acesso direto ao sistema e aos arquivos locais, e pros scripts que você mesmo escreveu

HTTP: o recomendado pra servidor remoto

O HTTP (streamable HTTP) é o transporte recomendado no Claude Code para servidores remotos e serviços em nuvem

Aqui não tem processo subindo na sua máquina: você aponta pra uma URL e o servidor vive do lado de lá

SSE: o remoto antigo, deprecado

O SSE é o transporte remoto legado, deprecado em favor do HTTP

E não é só decisão do produto: na própria especificação do MCP o HTTP+SSE legado está oficialmente deprecado e foi substituído pelo Streamable HTTP, que incorpora SSE apenas como mecanismo OPCIONAL de streaming. O stdio segue firme como transporte das integrações locais iniciadas como processo

Então, traduzindo a pergunta do título: MCP local ou remoto, no dia a dia, é stdio x HTTP

O SSE só entra se o fornecedor ainda não te deu outra opção

MCP local x MCP remoto: comparação ponto a ponto

Repare numa coisa: a linha do time é igual nos dois

Escopo é assunto separado de transporte, e misturar os dois é o que mais confunde quem está começando

Como adicionar cada tipo de servidor MCP no Claude Code

Comandos curtos, e em cada passo o erro que costuma pegar 😀

1. Adicione um servidor local (stdio) com o comando abaixo, lembrando do separador de dois hifens entre o nome e o comando que será executado (com os argumentos dele, se tiver)

claude mcp add <nome> -- <comando>

O erro comum deste passo: esquecer o separador. Ele é o que separa o nome do servidor do comando real, sem ele o Claude Code não tem como saber onde acaba uma coisa e começa a outra

2. Adicione um servidor remoto por HTTP, que é o transporte recomendado pra serviços em nuvem

claude mcp add --transport http <nome> <url>

O exemplo da própria doc usa o Sentry:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

O erro comum deste passo: escolher SSE por hábito (ou porque foi o que apareceu num tutorial antigo) quando o fornecedor já oferece endpoint HTTP

3. Use SSE só como legado, quando não existir alternativa

claude mcp add --transport sse <nome> <url>

O erro comum deste passo: tratar SSE como opção equivalente. Ele está deprecado em favor do HTTP, então é plano B, não escolha de gosto

4. Conclua o OAuth do servidor remoto, que é onde muita gente trava achando que o add já autenticou

Dentro da sessão interativa você roda:

/mcp

Ou, direto do terminal:

claude mcp login <nome>

O erro comum deste passo: achar que autenticar uma vez resolve pra sempre em qualquer lugar. O Claude Code guarda o login OAuth POR endpoint, então autenticar num projeto não vale automaticamente pra outro projeto que carrega uma definição diferente do servidor

5. Limpe as credenciais salvas quando trocar de conta ou quiser refazer o fluxo do zero

claude mcp logout <nome>

O erro comum deste passo: ficar tentando reautenticar por cima de uma credencial antiga em vez de sair primeiro

Quando o time inteiro precisa da mesma integração: escopo local, project e user

O Claude Code organiza servidores MCP em três escopos: local, project e user

E cada um responde a um cenário bem diferente

local: o padrão, só pra você

Quando você roda claude mcp add sem flag de escopo, cai no escopo local

Ele é privado e restrito ao projeto atual

É o lugar certo pra testar um servidor novo sem empurrar nada pra ninguém

project: o que o time compartilha

Com a flag de escopo project, a configuração é gravada em .mcp.json na raiz do repositório

E esse arquivo pode ser commitado, que é justamente como a integração vira padrão do time em vez de conhecimento tribal de quem configurou primeiro

Aqui entra um detalhe que salva a sua pele: o .mcp.json aceita expansão de variáveis de ambiente com a sintaxe ${VAR} e ${VAR:-default} nos campos command, args, env, url e headers

Ou seja, dá pra commitar a estrutura da configuração sem commitar a credencial junto, cada pessoa preenche a variável na máquina dela

Tome cuidado: por segurança, o Claude Code pede aprovação em sessão interativa antes de usar servidores de escopo project vindos do .mcp.json

Então o colega que clonou o repo não vai ver o servidor magicamente ativo, ele precisa aprovar

user: registrado uma vez, vale pra todos os seus projetos

Com a flag de escopo user, o servidor fica registrado uma vez pra todos os projetos do usuário

É o escopo pra aquela integração que você usa em TUDO, independente do repositório em que está trabalhando

Problemas comuns em cada tipo (e como prevenir)

A saída da ferramenta veio cortada

Sintoma: aparece um aviso quando a saída de uma ferramenta MCP passa de 10.000 tokens, e o resultado é limitado a 25.000 tokens por padrão

Causa: a ferramenta está devolvendo mais coisa do que o limite padrão permite

Solução: dá pra elevar o teto pela variável de ambiente MAX_MCP_OUTPUT_TOKENS

MAX_MCP_OUTPUT_TOKENS=50000

Detalhe importante: o limiar do AVISO é fixo, então mesmo elevando o limite você vai continuar vendo o aviso a partir dos 10.000 tokens

Prevenção: antes de sair aumentando o teto, pense se a ferramenta precisa mesmo cuspir tudo aquilo. Saída gigante entope o contexto, e isso conversa direto com o assunto de gastar menos com o Claude Code, onde contexto desperdiçado é dinheiro desperdiçado

O servidor do .mcp.json não aparece

Sintoma: você clonou o projeto, o .mcp.json está lá, e o servidor simplesmente não está disponível

Causa: servidores de escopo project vindos do .mcp.json passam por um prompt de aprovação em sessão interativa

Solução: aprove na sessão. Se você recusou antes e quer refazer a escolha:

claude mcp reset-project-choices

Prevenção: avise o time que existe esse passo de aprovação. Sem isso vira aquele chamado clássico de "aqui não funciona" 🙂

O OAuth está pedindo login de novo

Sintoma: você autenticou o servidor remoto ontem, abre outro projeto e ele pede autenticação de novo

Causa: as credenciais OAuth são armazenadas por endpoint, então uma definição diferente do servidor em outro projeto não herda o login

Solução: rode /mcp na sessão, ou claude mcp login com o nome do servidor, e conclua o fluxo ali

Prevenção: se o mesmo servidor remoto te acompanha em vários repositórios, considere registrar no escopo user em vez de repetir a configuração projeto a projeto

Veredito: qual tipo faz mais sentido no seu caso

Sem enrolação, por cenário:

• Ferramenta que lê e escreve no seu repositório, ou script próprio que você mantém: stdio. É o transporte indicado pra acesso direto ao sistema e a arquivos locais
• SaaS de terceiro que já publica um servidor oficial: HTTP. Você aponta a URL, usa o OAuth nativo do Claude Code e não fica gerenciando chave de API na mão
• Integração que TODO MUNDO do time precisa: escopo project com .mcp.json commitado, independente do transporte ser stdio ou HTTP
• Fornecedor que só oferece SSE: vai de SSE ciente de que é o caminho legado, e migre quando ele publicar endpoint HTTP

O trade-off central é esse: de um lado controle e acesso local, com a manutenção sendo sua; do outro menos manutenção, porque updates, escala e disponibilidade ficam com o fornecedor, em troca de depender dele

Não existe resposta única, existe o que o seu caso pede

E, sinceramente, antes de montar integração pra tudo vale a leitura sobre quando não usar o Claude Code, porque nem todo problema vira MCP

Próximo passo

Resumindo em uma frase: stdio quando a ferramenta precisa da sua máquina, HTTP quando ela vive na nuvem, e escopo project quando a integração precisa ser de todo mundo

A ação imediata é a mais barata possível: adicione o servidor no escopo local (que é o padrão, lembra?), valide com /mcp dentro da sessão e só depois promova pra project ou user, quando a integração provar que vale a pena

Testar pequeno primeiro evita aquele .mcp.json commitado que ninguém consegue fazer funcionar…

até o próximo post! 😀