Localização do mcp.json no VS Code: configuração e registro de servidores MCP, passo a passo

Você adiciona um servidor MCP ao VS Code, recarrega a janela, abre o Copilot Chat e as novas ferramentas não aparecem em lugar nenhum. Na maioria das vezes o servidor está bem e o problema é o arquivo: ele está na pasta errada, usa a propriedade de nível superior errada, ou o VS Code está lendo uma cópia diferente da que você acabou de editar. Este artigo define a localização do mcp.json no VS Code para cada configuração, mostra o formato JSON que o editor espera e explica como o registro MCP se encaixa, para que você adicione servidores sem copiar comandos de READMEs aleatórios.

O Model Context Protocol (MCP) é o padrão aberto que permite a um assistente de IA chamar ferramentas externas: ler uma pasta, consultar um banco de dados, abrir um pull request. O VS Code atua como cliente MCP, e cada servidor que você ativa aparece como um conjunto de ferramentas no modo agente. Toda a configuração fica em um único arquivo JSON pequeno, e é exatamente por isso que um caminho errado ou um nome de propriedade errado falha de forma tão silenciosa.

Onde o mcp.json fica

O VS Code lê as definições de servidores MCP em dois lugares principais, além de um formato portável descrito mais adiante. Pense neles como uma prateleira da equipe e uma prateleira pessoal.

Arquivo do workspace: .vscode/mcp.json

O arquivo do workspace fica dentro da pasta do projeto, em .vscode/mcp.json. Crie a pasta .vscode se ela não existir, coloque o arquivo nela, e o VS Code o encontra. Como ele acompanha o repositório, todos que clonarem o projeto terão a mesma lista de servidores.

Você também pode abri-lo pela Paleta de Comandos (Ctrl+Shift+P no Windows e Linux, Cmd+Shift+P no macOS) com MCP: Open Workspace Folder Configuration, ou criar uma entrada com MCP: Add Server e escolher a opção do workspace.

Arquivo do usuário por sistema operacional

O arquivo do usuário vale para todas as janelas que você abrir. A forma mais rápida de chegar até ele é o comando da Paleta de Comandos MCP: Open User Configuration, que abre a cópia pertencente ao seu perfil ativo. Em uma instalação padrão, o arquivo fica na pasta de dados do usuário do VS Code:

💡 Dica: O VS Code Insiders mantém sua própria pasta de dados, geralmente chamada Code - Insiders em vez de Code. Se uma edição não muda nada, verifique se você não está editando a cópia estável enquanto executa o Insiders. Na dúvida, confie no comando da Paleta de Comandos em vez de qualquer caminho que você tenha digitado de memória.

Qual escolher

A escolha depende de quem precisa do servidor e de ele carregar ou não um token pessoal.

Evite definir o mesmo nome de servidor nos dois arquivos. Com duas cópias, você não consegue mais saber qual delas está de fato em execução, e um relato de bug que diz "o servidor está quebrado" vira uma tarde inteira de adivinhação.

Escrevendo o formato do arquivo corretamente

O arquivo tem até três seções de nível superior: servers (obrigatória, um mapa de nomes de servidores para configurações), inputs (opcional, prompts para valores que você não quer armazenar) e sandbox (opcional, regras de arquivos e rede no macOS e Linux). Todo o resto depende dessas três.

Um servidor stdio mínimo

Um servidor stdio é um programa que o VS Code inicia na sua máquina e com o qual se comunica por entrada e saída padrão. A maioria dos servidores da comunidade é distribuída assim, geralmente por meio do npx ou do uvx.

{
  "servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]
    }
  }
}

Copiar prompt

A variável ${workspaceFolder} se expande para o projeto aberto, então o mesmo arquivo funciona na máquina de cada colega. Você pode adicionar cwd para o diretório de trabalho, env para variáveis de ambiente e envFile para carregar variáveis de um arquivo.

Um servidor HTTP remoto

Um servidor remoto roda em outro lugar, e o VS Code se conecta à URL dele. Sem processo local, sem npx, sem problemas de versão do Node.

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

Copiar prompt

Use "type": "http" para servidores remotos atuais e "type": "sse" para servidores que ainda usam o transporte mais antigo de eventos enviados pelo servidor. As entradas remotas também podem ter headers para autenticação e um objeto oauth quando o servidor oferece login pelo navegador.

A armadilha de servers ou mcpServers

Este é, de longe, o motivo mais comum de uma configuração copiada não fazer nada.

Por que seu servidor nunca aparece

A maioria dos READMEs mostra um trecho escrito para o Claude Desktop, o Claude Code ou o Cursor. Esses clientes usam uma propriedade de nível superior chamada mcpServers. O próprio mcp.json do VS Code espera servers. Se você colar o formato errado em .vscode/mcp.json, o arquivo pode falhar em silêncio: o editor pode marcar a propriedade, mas o aviso é fácil de passar despercebido, e nenhuma ferramenta aparece.

{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] }
  }
}

Copiar prompt

Esse bloco pertence a outro cliente. Para o VS Code, renomeie a propriedade de nível superior para servers e adicione "type": "stdio" para que a entrada siga o formato mostrado antes.

O VS Code também documenta um formato portável: um arquivo .mcp.json na raiz do projeto, ou ~/.copilot/mcp-config.json para o usuário. Esses arquivos portáveis usam mcpServers. A regra é simples: servers dentro do mcp.json do VS Code, mcpServers dentro dos arquivos portáveis.

Nomes de propriedade por cliente

Passe por esta lista curta sempre que as ferramentas sumirem:

• Verifique o nome da propriedade primeiro. servers para mcp.json, mcpServers para arquivos portáveis.
• Verifique o type. Um programa local precisa de stdio, uma URL precisa de http ou sse.
• Verifique o arquivo que você abriu. Execute MCP: List Servers e confirme se o seu servidor aparece ali.
• Recarregue a janela depois de uma edição grande, se a lista de servidores parecer desatualizada.

Mantenha os segredos fora do arquivo

Um mcp.json do workspace geralmente vai parar no Git. Tudo o que você digitar nele, inclusive um token, vai parar ali também.

Peça tokens com inputs

A seção inputs define valores que o VS Code pede em vez de armazená-los. Referencie um deles em qualquer entrada de servidor com ${input:id}.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "api-token",
      "description": "API token for the image service",
      "password": true
    }
  ],
  "servers": {
    "image-service": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${input:api-token}" }
    }
  }
}

Copiar prompt

A URL acima é um exemplo. O que importa é o padrão: promptString com password: true mostra um campo mascarado, o VS Code pede o valor quando o servidor inicia, e o token nunca precisa ficar no arquivo. Existem outros dois tipos de input: pickString para uma lista fixa de opções, e command para um valor gerado pela execução de um comando.

💡 Dica: O mesmo padrão serve para qualquer serviço REST que use token Bearer, inclusive a API para desenvolvedores do Picasso IA em api.picassoia.com/v1, cujos tokens começam com pia_sk_. Guarde esse token em um input ou em uma variável de ambiente, nunca em um arquivo versionado.

envFile e confiança no workspace

Para servidores stdio, envFile carrega variáveis de um arquivo como ${workspaceFolder}/.env. Adicione esse arquivo a .gitignore antes do primeiro commit, e não depois.

A confiança funciona em duas camadas. Servidores definidos no workspace herdam o Workspace Trust, então uma pasta não confiável não os inicia. Servidores definidos fora do workspace disparam o próprio aviso de confiança na primeira vez que rodam. A configuração chat.mcp.autostart controla os reinícios quando uma configuração muda, com os valores never, onlyNew e newAndOutdated (o padrão).

Encontrando servidores no registro

Escrever cada entrada à mão cansa rápido. O VS Code oferece duas formas de evitar isso.

Navegue com @mcp em Extensions

Abra a visualização de Extensions (Ctrl+Shift+X) e digite @mcp na caixa de busca. A lista que aparece é a galeria de servidores MCP dentro do editor. Escolha um, decida se quer instalá-lo no perfil do usuário ou no workspace, e o VS Code adiciona a entrada ao mcp.json correspondente. Depois, abra o arquivo e leia o que foi escrito. É uma boa forma de ver a sintaxe correta dos servidores que você vai adicionar manualmente mais tarde.

O que o registro oficial acrescenta

O Registro Oficial do MCP é o diretório público em que os autores publicam seus servidores. Cada entrada informa o pacote ou a URL remota, exatamente o que você colaria em mcp.json por conta própria. Use-o quando um servidor não estiver na galeria de Extensions, e confira o nome do pacote com a entrada do registro antes de executar qualquer coisa. Um erro de digitação em um argumento de npx pode instalar outro pacote.

Detecção automática de servidores de outros apps

O VS Code também pode importar servidores que você já configurou em outras ferramentas. Abra as Configurações, pesquise por chat.mcp e procure a opção que controla a detecção automática de outros aplicativos. Se quiser começar do zero, desative-a. Se você veio do Claude Desktop, mantê-la ligada poupa o trabalho de digitar tudo de novo.

Corrija um servidor que não inicia

Quando um servidor mostra erro, a resposta quase sempre está no próprio log.

Leia o log de saída

Execute MCP: List Servers, selecione o servidor e abra a saída dele. Você também pode abrir mcp.json e olhar acima do nome do servidor, onde o VS Code mostra ações inline para iniciar, parar, reiniciar e mostrar a saída. O log imprime o comando exato que o VS Code executou e tudo o que o processo escreveu na saída de erro padrão. Leia o primeiro erro, não o último.

Padrões comuns de falha

Modo de desenvolvimento e sandbox

Se você cria servidores, o objeto dev em uma entrada stdio ajuda. watch recebe um padrão glob e reinicia o servidor quando arquivos correspondentes mudam, e debug conecta um depurador (Node.js e Python são suportados para servidores stdio). No macOS e Linux, o objeto sandbox restringe o que um servidor pode tocar: filesystem.allowWrite, filesystem.denyRead, filesystem.denyWrite, network.allowedDomains e network.deniedDomains. Defina sandboxEnabled em um servidor específico para aplicá-lo. Comece restrito e libere só o que o servidor comprovar que precisa.

Rascunhe sua configuração com o Claude Sonnet 5

Se um modelo de linguagem vai ajudar com o JSON, escolha um modelo feito para código. O Claude Sonnet 5 no Picasso IA escreve e depura código, lê capturas de tela e deixa você escolher o quanto ele pensa antes de responder. Este é o fluxo de trabalho que funciona para mcp.json.

1. Abra a página do modelo. Acesse Claude Sonnet 5 no Picasso IA.
2. Preencha o System Prompt uma vez. Algo como: You write VS Code mcp.json files. Use the servers property, never mcpServers. Always set type. Output JSON only.
3. Descreva a configuração no Prompt. Diga os servidores que você quer, o sistema operacional e se cada um deve ser stdio ou remoto.
4. Defina effort. Deixe em low para uma correção de uma linha. Use medium ou high quando o arquivo combinar vários servidores e inputs. A configuração low desliga o pensamento, então é a opção mais rápida e mais barata.
5. Mantenha o Max Tokens no padrão de 8192. Um arquivo de configuração precisa de bem menos.
6. Anexe uma captura de tela se houver erro. O campo opcional Image aceita uma imagem, e o Max Image Resolution vem em 0,5 megapixel por padrão para manter o custo baixo.
7. Execute e depois verifique. Cole o resultado em mcp.json, compare cada nome de pacote e URL com a entrada do registro e acompanhe o log de saída na primeira inicialização.

Um prompt que gera um primeiro rascunho utilizável:

Create a VS Code mcp.json for Windows with two servers: a stdio filesystem
server limited to the workspace folder, and a remote HTTP server at
https://mcp.example.com/mcp that needs a Bearer token. Ask for the token
with an input so it is never stored in the file.

Copiar prompt

💡 Dica: Modelos podem inventar nomes de pacotes que parecem corretos, mas não existem. Trate qualquer array args gerado como rascunho até conferi-lo com o registro.

Outros modelos de chat e de código da plataforma fazem o mesmo trabalho, então teste alguns e fique com o que segue melhor o seu system prompt:

Crie seus próprios visuais com o Picasso IA

Uma configuração MCP bem-feita merece uma documentação que as pessoas realmente leiam. Um README com uma imagem de destaque clara, um diagrama que mostre como seus servidores se conectam ou a miniatura de um tutorial curto deixam a página de configuração com aparência finalizada. O Picasso IA consegue produzir todos eles.

Comece com o Picasso IA Image para um primeiro rascunho rápido, teste o GPT Image 2 quando seu visual precisar de texto legível, e use o Picasso IA Image Editor Pro para ajustar uma imagem que você já tem. Para cenas fotorrealistas, vale testar o Seedream 4.5. A plataforma também inclui texto para vídeo e outros geradores, e você pode navegar por todas as opções na página de todos os modelos.

Escreva um prompt, gere algumas variações, escolha a que combina com sua página e coloque-a na sua documentação. A melhor forma de descobrir o que funciona para o seu projeto é testar, então abra o Picasso IA, digite uma cena que você quer ver e crie sua primeira imagem hoje.