MCP no Claude Code e no Cursor: o que é e como configurar

O resumo direto

MCP (Model Context Protocol) é um padrão aberto que liga um agente de IA a ferramentas e dados externos, útil para quem já escreve código com Claude Code ou Cursor e quer que o agente consulte sistemas reais em vez de receber texto colado no chat. A documentação oficial o descreve como "an open-source standard for connecting AI applications to external systems" e usa a analogia da porta USB-C: um conector, vários aparelhos. Na prática, toda a configuração cabe em dois arquivos JSON: .cursor/mcp.json no Cursor e .mcp.json no Claude Code. O agente lê esse arquivo, sobe o servidor e passa a enxergar as ferramentas expostas. Quase todo problema de estreia cai no mesmo ponto: o servidor local não sobe porque o comando não está no PATH do editor ou porque a versão do Node é antiga demais. Abaixo estão as duas configurações, com o Shopify Dev MCP de exemplo, e a separação entre erro de arquivo e erro de ambiente.

1. O que é MCP em três camadas

A documentação de arquitetura do protocolo separa o assunto em partes que vale guardar, porque cada erro aparece em uma delas.

Participantes. Existe o host (a aplicação de IA, como o Claude Code ou o Cursor), o cliente (uma conexão dedicada por servidor) e o servidor (o programa que entrega contexto e ferramentas). O host abre um cliente por servidor configurado, e é por isso que um servidor quebrado não derruba os outros.

Camada de dados. Protocolo baseado em JSON-RPC 2.0. Nele vivem os primitivos do servidor: tools (funções executáveis), resources (fontes de dados) e prompts (modelos de interação). O cliente descobre o que existe com chamadas de listagem e executa com tools/call.

Camada de transporte. Define por onde as mensagens trafegam. São dois transportes: stdio, que usa entrada e saída padrão entre processos na mesma máquina, e Streamable HTTP, que usa POST com Server-Sent Events opcional e aceita bearer token, API key ou headers. A recomendação oficial para obter token é OAuth.

O protocolo é versionado por data. A versão atual é 2026-07-28, e o número só muda quando há quebra de compatibilidade. A negociação acontece por requisição, e o servidor recusa a versão que não suporta.

2. Os dois transportes e quando usar cada um

O transporte decide onde o código roda, quem paga a infraestrutura e como você autentica. O Cursor documenta a comparação assim:

Fonte: Cursor Docs, página Model Context Protocol (MCP), lida em 21/09/2026.

Regra prática: stdio para ferramenta que toca no seu disco, no seu banco local ou em um script seu. HTTP para serviço de terceiro na nuvem e para time, porque um servidor atende vários clientes e a autenticação segue OAuth em vez de variável de ambiente espalhada por máquina.

O Claude Code documenta HTTP como opção recomendada para servidores remotos e marca SSE como transporte descontinuado. Servidores que só expõem SSE continuam funcionando: versões recentes tentam HTTP primeiro e trocam para SSE quando o servidor não aceita.

3. Onde fica a configuração de verdade

Botão de instalação em marketplace é conveniência. O que manda é o arquivo, e saber qual arquivo o agente leu resolve metade dos problemas.

Cursor

Dois lugares, e a diferença é o alcance:

• .cursor/mcp.json na raiz do projeto: vale só naquele projeto.
• ~/.cursor/mcp.json na home: vale em qualquer projeto.

Um servidor stdio no Cursor usa os campos type, command, args, env e envFile. A documentação é explícita sobre o command: ele "must be available on your system path or contain its full path". Guarde essa frase, porque é a causa do erro da seção 5. O envFile só existe para stdio.

Claude Code

Três escopos, e cada um grava em um lugar diferente:

Fonte: documentação do Claude Code, página de MCP, lida em 21/09/2026.

O arquivo que você comita é o .mcp.json. Ele usa a mesma chave mcpServers que o Cursor, o que permite copiar um bloco de um para o outro na maioria dos casos. Por segurança, o Claude Code pede aprovação interativa antes de usar servidores vindos de .mcp.json: repositório clonado não liga servidor sozinho.

Quando o mesmo nome aparece em mais de um escopo, o Claude Code conecta uma vez só, pela definição de maior precedência, sem misturar campos. A ordem é local, project, user, servidores de plugin e conectores.

4. Configurando na prática: o mesmo servidor nos dois editores

O exemplo usa o Shopify Dev MCP, servidor oficial que dá ao agente acesso à documentação de desenvolvedor, aos schemas de API e à validação de GraphQL, Liquid e extensões. Serve de exemplo porque roda local, por stdio, e não pede autenticação.

Requisito antes de qualquer arquivo

O Shopify AI Toolkit pede Node.js 18 ou superior. Confirme a versão no mesmo shell que abre o editor:

node -v
npx -y @shopify/dev-mcp@latest --help

Se o segundo comando não responder, o problema é ambiente, não JSON. Resolva aqui antes de editar configuração.

Claude Code

A forma documentada usa o CLI, que escreve a configuração por você:

claude mcp add --transport stdio shopify-dev-mcp \
  -- npx -y @shopify/dev-mcp@latest

O -- separa as opções do Claude Code do comando que sobe o servidor. Sem ele, o CLI lê as flags do servidor, como -y, como se fossem dele. Para compartilhar com o time, acrescente --scope project, que grava em .mcp.json.

O arquivo resultante, se preferir escrever à mão na raiz do projeto:

{
  "mcpServers": {
    "shopify-dev-mcp": { "command": "npx", "args": ["-y", "@shopify/dev-mcp@latest"] }
  }
}

Depois disso, reinicie o Claude Code para carregar a configuração nova. Dentro da sessão, /mcp mostra o painel com status e contagem de ferramentas por servidor.

Cursor

Mesmo bloco, em .cursor/mcp.json na raiz do projeto:

{
  "mcpServers": {
    "shopify-dev-mcp": { "command": "npx", "args": ["-y", "@shopify/dev-mcp@latest"] }
  }
}

Salve e reinicie o Cursor. Em Windows, a documentação da Shopify registra uma alternativa para quando aparece erro de conexão: trocar o command por cmd e passar ["/k", "npx", "-y", "@shopify/dev-mcp@latest"] em args.

Verificação

No Claude Code, claude mcp list mostra o status de cada servidor: conectado, precisa de autenticação ou falhou ao conectar. No Cursor, o servidor aparece no painel de ferramentas do chat, e o log fica em Output, opção MCP Logs.

5. O erro clássico: o servidor stdio que não sobe

Servidor remoto falha com status HTTP, que é legível. Servidor stdio falha em silêncio, e quase sempre por um destes motivos.

PATH diferente do que você vê no terminal

Um servidor stdio é um processo que o editor dispara, e ele herda o ambiente do editor, não o do seu terminal. Se você instalou Node por nvm, asdf, Volta ou Homebrew e abriu o editor pelo ícone da área de trabalho, o npx que funciona no terminal pode não existir para o editor. É o que a documentação do Cursor previne ao exigir command no PATH do sistema ou com caminho completo.

Duas saídas. A direta é descobrir o caminho absoluto e usá-lo:

which node
which npx

E então trocar "command": "npx" por esse caminho absoluto no JSON. A outra é abrir o editor a partir do terminal já configurado, para que o processo herde o PATH certo.

Versão de Node abaixo do exigido

O toolkit da Shopify exige Node.js 18 ou superior. Com nvm, a versão ativa no terminal não é necessariamente a que o editor enxerga. O sintoma é um servidor que aparece como falho sem mensagem clara, ou que morre logo após subir. Rode node -v pelo caminho absoluto que você colocou no JSON, não pelo do seu shell.

Entrada com url e sem type

Erro de arquivo, não de ambiente. O Claude Code lê entrada sem type como servidor stdio. Logo, entrada com url e sem type é configuração inválida: o servidor é pulado e a mensagem é MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry. Em versões anteriores à 2.1.202, a mesma configuração aparecia como command: expected string, received undefined, o que manda o dev procurar no lugar errado. Ao copiar um bloco mcpServers escrito para outro cliente, confira se as entradas com url declaram type.

Espaço invisível em token colado

O Claude Code avisa quando um valor de configuração carrega espaço em branco no começo ou no fim, típico de token colado com quebra de linha. A verificação cobre command, url, cada item de args e os valores e nomes de chave em env e headers. O aviso nomeia o campo sem imprimir o valor, e o agente não corta o espaço sozinho. Corrija no arquivo.

Tempo de partida curto

Servidor que baixa pacote no primeiro npx demora mais que o normal. No Claude Code, o tempo de partida é configurável por variável de ambiente:

MCP_TIMEOUT=10000 claude

O valor é em milissegundos, então esse exemplo dá dez segundos para o servidor subir.

Reconexão que não existe

Servidores remotos que caem no meio da sessão são reconectados pelo Claude Code com backoff exponencial, até cinco tentativas. Servidores stdio não: são processos locais e não têm reconexão automática. Se o processo morreu, reconecte pelo painel /mcp ou reinicie a sessão.

6. Segredo, escopo e o que não comitar

.mcp.json na raiz é feito para ir ao repositório, e é aí que o risco aparece: chave de API escrita direto no JSON vai junto no commit.

Os dois editores resolvem isso com interpolação. O Cursor resolve variáveis em command, args, env, url e headers, com as sintaxes ${env:NOME}, ${userHome} e ${workspaceFolder} (a pasta que contém .cursor/mcp.json). O Claude Code expande ${VAR} e aceita valor padrão na forma ${VAR:-default}.

O bloco compartilhado referencia a variável e cada pessoa do time define o valor na própria máquina:

{ "mcpServers": {
  "api-interna": {
    "type": "http", "url": "https://api.exemplo.com/mcp",
    "headers": { "Authorization": "Bearer ${env:API_TOKEN}" }
  }
} }

Três cuidados que valem mais que qualquer truque de configuração:

1. Chave com permissão mínima. Se o agente só precisa ler pedido, a chave não precisa criar cliente.
2. Servidor de terceiro é código executando na sua máquina, com seu acesso. A documentação do Claude Code é direta ao pedir que você verifique se confia no servidor antes de conectar, porque servidores que buscam conteúdo externo expõem você a risco de prompt injection. O Cursor recomenda revisar o código-fonte em integrações críticas.
3. Ambiente sensível pede stdio local em vez de endpoint remoto, conforme a própria recomendação do Cursor sobre dados sensíveis.

7. Limites que aparecem quando o servidor funciona

Servidor conectado não significa fluxo resolvido. Dois limites documentados aparecem rápido em uso real.

Volume de saída. O Claude Code avisa quando a saída de uma ferramenta MCP passa de 10.000 tokens e limita a saída a 25.000 tokens por padrão. Dá para elevar o teto com MAX_MCP_OUTPUT_TOKENS; o limiar do aviso é fixo. Ferramenta que devolve dump inteiro de tabela bate nesse teto, e a saída costuma ser filtrar no servidor, não aumentar o limite.

Inatividade por chamada. Uma chamada que não responde nem envia notificação de progresso dentro da janela de inatividade aborta com erro em vez de esperar o limite de relógio. A janela padrão é de cinco minutos para HTTP, SSE, WebSocket e conectores, e de 30 minutos para stdio. Trabalho longo exige servidor que emita progresso.

Fonte: documentação do Claude Code, página de MCP, lida em 21/09/2026.

Se o seu uso é rodar agente em máquina que fica ligada o tempo todo, a lógica de ambiente e PATH desta seção vale igual, e o assunto de manter o Claude Code em servidor está em Claude Code 24/7 numa VPS Hostinger.

Perguntas frequentes

MCP substitui a API do sistema que eu quero integrar?

Não. MCP é a camada de conexão entre agente e ferramenta; a API continua sendo a API. O servidor MCP fala com o seu sistema e expõe aquilo como tools, resources ou prompts. Se o sistema não tem API nem banco acessível, MCP não cria acesso que não existe.

Posso usar a mesma configuração no Cursor e no Claude Code?

Na maior parte dos casos, sim: os dois leem a chave mcpServers com o mesmo formato. A documentação do Claude Code aponta os dois reparos comuns ao aproveitar bloco escrito para outro cliente: acrescentar type em entrada com url e trocar nome de servidor com caracteres fora de letras, números, hífen e sublinhado.

Por que o servidor funciona no terminal e falha dentro do editor?

Porque o processo do servidor herda o ambiente do editor, não o do seu terminal. Gerenciadores de versão de Node mudam o PATH por shell, e o editor aberto por ícone não passa por esse shell. Use o caminho absoluto no campo command ou abra o editor pelo terminal já configurado.

Servidor MCP de terceiro é seguro?

Depende de quem publicou e do que ele acessa. A documentação do Claude Code pede que você verifique se confia no servidor antes de conectar, porque servidores que trazem conteúdo externo criam risco de prompt injection. O Cursor recomenda instalar de origem confiável, revisar o que o servidor acessa, usar chave com permissão restrita e ler o código nas integrações críticas.

Preciso de MCP para o agente entender meu projeto Shopify?

Não necessariamente. A Shopify oferece o toolkit por plugin, por agent skills e por Dev MCP, e trata o plugin como caminho recomendado, com atualização automática. MCP é o caminho quando o agente precisa falar com um sistema que só você tem, como ERP, banco interno ou painel próprio.

Conclusão

MCP resolve um problema específico: dar ao agente um caminho padronizado até a ferramenta, em vez de você colar dado no chat. A configuração é pequena e vive em dois arquivos, .cursor/mcp.json e .mcp.json, com a mesma chave mcpServers. O que quebra quase nunca é o JSON em si: é o comando que não está no PATH do editor, a versão de Node abaixo do exigido ou a entrada com url e sem type. Comece por um servidor só, verifique o status antes de pedir qualquer coisa ao agente e só depois some o segundo.

Se o que você precisa é o agente lendo o seu ERP, a sua loja ou o seu banco, isso é integração sob medida (MCP, webhook, fila). Descreve o sistema e o que quer automatizar em oailton.dev/contato.