Tutorial

Como configurar servidores MCP no Windows

A maioria dos guias de MCP presume um Mac e um arquivo JSON. Este é para o Windows, com o Conduit, um app de IA para desktop gratuito e de código aberto, como cliente: o que instalar, o que digitar em cada campo e o que os erros significam quando um servidor não inicia.

Introdução

O Model Context Protocol (MCP) permite que um app de IA use ferramentas de outros programas: ler e gravar arquivos, pesquisar documentação, consultar um banco de dados, abrir issues. Cada conjunto de ferramentas vem de um servidor MCP. Um servidor local é um programa que o app inicia no seu computador, geralmente com npx (Node.js) ou uvx (Python). Um servidor remoto roda em outro lugar e é acessado por URL.

No Windows, os servidores locais falham por alguns motivos previsíveis: o ambiente de execução não está instalado ou não está no PATH, o app tenta executar um script de shell como se fosse um programa, ou o caminho de uma pasta tem um espaço. Este tutorial evita cada um deles.

Você vai instalar o Node.js e o uv, adicionar o servidor oficial Filesystem com o npx e o servidor Fetch com o uvx, e adicionar o Microsoft Learn, um servidor remoto para a documentação da Microsoft. Depois vai usá-los num chat, aprovar uma ferramenta que altera um arquivo e ver como é um servidor que não inicia e como corrigi-lo. No Conduit, os servidores MCP se chamam conectores.

Principais conclusões

Pré-requisitos

Para acompanhar este tutorial, você vai precisar de:

Passo 1 — Instalando o Node.js e o uv

A maioria dos servidores MCP locais são pacotes do Node.js, iniciados com npx, ou pacotes do Python, iniciados com uvx. Neste passo, você vai instalar os dois ambientes de execução.

Abra o PowerShell e execute:

winget install OpenJS.NodeJS.LTS
winget install astral-sh.uv

O uv baixa a versão do Python de que cada servidor precisa, então você não instala o Python separadamente. Feche o PowerShell, abra uma janela nova e confira se os dois são encontrados:

npx --version
uvx --version

Cada um mostra um número de versão. Se o PowerShell disser que o comando não é reconhecido, saia do Windows e entre de novo, para que o novo PATH valha, e tente outra vez.

Por fim, feche o Conduit e abra-o de novo, inclusive pela bandeja do sistema, se ele ainda estiver rodando lá. Um programa enxerga o PATH com que foi iniciado, então um Conduit que estava aberto durante as instalações ainda não encontra o npx nem o uvx.

A seguir, você vai adicionar o primeiro servidor.

Passo 2 — Adicionando um servidor local com o npx

O servidor Filesystem dá ao assistente ferramentas para listar, ler, pesquisar e gravar arquivos, mas só dentro das pastas que você indicar. Neste passo, você vai adicioná-lo para uma pasta.

Escolha Contexto na barra lateral, depois Conectores no alto e Adicionar conector. O painel tem três formas de adicionar um servidor: Registro oficial do MCP, Servidor remoto por URL e Comando local. Em Comando local, preencha:

  1. Nome do conector: Filesystem.
  2. Comando: npx.
  3. Argumentos: -y @modelcontextprotocol/server-filesystem C:\Users\Public\Documents\Northwind, com a sua própria pasta no final. O -y deixa o npx baixar o pacote sem perguntar.

Deixe Ambiente vazio; este servidor não precisa de chaves. Escolha Adicionar conector local. O conector aparece na lista como parado. Escolha Iniciar.

A primeira inicialização demora um pouco mais, enquanto o npx baixa o pacote. Depois o status muda para ativo e as ferramentas do servidor são listadas, cada uma marcada com o que faz:

As ferramentas Só lê rodam sem perguntar. As ferramentas Faz alterações, pergunta antes pedem a sua aprovação a cada vez, até você mandar o Conduit lembrar. O Conduit toma esses rótulos do que o servidor declara sobre cada ferramenta.

O Conduit inicia o servidor sem janela de console. O comando é executado diretamente, nunca por um shell, e por isso o npx funciona aqui sem cmd /c: o Conduit procura o nome no PATH por conta própria e encontra o npx.cmd.

A seguir, você vai adicionar um servidor Python.

Passo 3 — Adicionando um servidor local com o uvx

Os servidores Python funcionam do mesmo jeito, com o uvx como comando. Neste passo, você vai adicionar o servidor Fetch, que baixa uma página da web e a transforma em Markdown.

Escolha Adicionar conector de novo. Em Comando local, digite Fetch como nome, uvx como comando e mcp-server-fetch como argumentos:

Escolha Adicionar conector local e depois Iniciar. A primeira inicialização baixa o servidor e seus pacotes Python, o que leva alguns segundos, e o conector fica ativo com uma ferramenta, fetch.

Observação: O Conduit já tem pesquisa na web e leitura de páginas próprias. O Fetch está aqui como exemplo de servidor Python; qualquer servidor publicado para o uvx é adicionado do mesmo jeito.

A seguir, você vai adicionar um servidor que roda remotamente.

Passo 4 — Adicionando um servidor remoto

Um servidor remoto não exige nada instalado. Neste passo, você vai adicionar o Microsoft Learn, o servidor oficial da Microsoft para pesquisar a documentação dela, que não exige conta.

Você encontra servidores remotos no registro oficial do MCP. Em Adicionar conector, digite uma palavra em Registro oficial do MCP e escolha Pesquisar:

Instalar adiciona um servidor da lista. O registro é aberto a qualquer pessoa, então veja quem publica um servidor antes de instalá-lo. Se você souber o endereço do servidor, pode adicioná-lo diretamente. Em Servidor remoto por URL, digite Microsoft Learn como nome e https://learn.microsoft.com/api/mcp como URL:

Escolha Adicionar conector remoto e depois Iniciar. O conector fica ativo com três ferramentas para pesquisar a documentação, encontrar exemplos de código e ler uma página, todas marcadas Só lê.

Um servidor remoto que exige uma conta mostra entrar em vez de iniciar. Escolha Entrar no conector, conclua o login no navegador, e o Conduit guarda o acesso que recebeu.

A seguir, você vai usar os servidores num chat.

Passo 5 — Usando os servidores num chat

Neste passo, você vai fazer uma pergunta que um conector responde e depois pedir uma alteração que precisa da sua aprovação.

Escolha Chats e Novo chat. O Conduit dá ao modelo um jeito de procurar as ferramentas dos conectores quando precisar, então você não precisa ativar nada. O modo mais confiável de fazer um servidor específico ser usado é citá-lo pelo nome. Envie:

Use o conector Microsoft Learn: como verifico qual versão do PowerShell estou
usando e como a atualizo no Windows 11? Coloque links das páginas que usou.

Cada chamada de ferramenta é uma linha na resposta, com o conector e o nome da ferramenta, o que foi pedido e quanto tempo levou. Clique em uma para ver exatamente o que foi enviado e o que voltou. As buscas só leem, então rodaram sem perguntar.

Agora peça algo que altere um arquivo. Num novo chat, envie:

Use o conector Filesystem: liste os arquivos em C:\Users\Public\Documents\Northwind
e depois crie ali um arquivo chamado reading-list.md que liste cada PDF com uma
descrição de uma linha do que ele provavelmente aborda, com base no nome.

Listar a pasta só lê, então roda. Gravar o arquivo para e espera por você:

O pedido mostra a ferramenta, a descrição que o próprio servidor dá dela e os dados que serão enviados, incluindo o caminho e o conteúdo a ser gravado. Negar interrompe. Marque Lembrar para este chat para deixar essa ferramenta rodar de novo neste chat sem perguntar, ou Sempre permitir esta ferramenta para todos os chats, e depois escolha Aprovar e executar.

O arquivo agora está na pasta. Para rever ou retirar depois uma aprovação lembrada, abra o conector na página Conectores e use Esquecer em Aprovações de ferramentas lembradas.

Passo 6 — Corrigindo um servidor que não inicia

Neste passo, você vai ver como é um servidor que falhou e como descobrir o motivo.

Um servidor que encerra assim que inicia aparece como fora do ar, com o motivo que o Conduit viu:

connector stdout closed (child exited) quer dizer que o servidor iniciou e depois encerrou, em geral com um erro que ele imprimiu. Para ver esse erro, execute o mesmo comando e os mesmos argumentos no PowerShell. Para o conector acima:

npx -y @modelcontextprotocol/server-filesystem C:\Users\Public\Shared Files
Warning: Cannot access directory C:\Users\Public\Shared, skipping
Error: None of the specified directories are accessible

O caminho tem um espaço, então chegou como dois argumentos, C:\Users\Public\Shared e Files, e nenhum dos dois é uma pasta. As causas mais comuns entre usuários do Windows:

O que você vê Causa Solução
spawn 'npx' failed O Node.js não está instalado, ou o Conduit foi iniciado antes dele. Instale-o (passo 1), depois feche o Conduit por completo e abra-o de novo.
O comando é recusado O comando é um shell, como cmd, powershell ou wsl. O Conduit não executa comandos por um shell. Coloque o próprio programa em Comando: npx, uvx, node, python ou o caminho completo de um .exe.
fora do ar com um argumento de pasta O caminho tem um espaço. Os Argumentos são separados em cada espaço. Use uma pasta cujo caminho não tenha espaços, como C:\Users\Public\Documents\Projects.
fora do ar num servidor que exige uma chave A chave está faltando. Adicione-a em Ambiente como uma linha KEY=VALUE, com o nome da variável da documentação do servidor.

Para mudar o comando ou os argumentos de um conector, adicione-o de novo com os novos valores, depois abra o antigo e escolha Revogar, que o interrompe e desativa suas ferramentas.

Perguntas

Preciso do Node.js e do Python para usar servidores MCP?

Só para os servidores locais escritos neles. Um servidor iniciado com npx precisa do Node.js, e um iniciado com uvx precisa do uv, que baixa o próprio Python. Servidores remotos, adicionados por URL ou pelo registro, rodam em outro lugar e não exigem nada instalado. O próprio Conduit não precisa de nenhum dos dois.

Posso reaproveitar a minha configuração MCP do Claude Desktop?

Não importando o arquivo, mas os mesmos valores funcionam. Para cada servidor do claude_desktop_config.json, coloque command em Comando, os itens de args em Argumentos, separados por espaços, e cada entrada de env como uma linha KEY=VALUE em Ambiente.

Posso adicionar um servidor remoto que exige uma chave de API?

Só se ele usar login por OAuth. O Conduit entra nos servidores remotos com OAuth pelo navegador, com o botão Entrar do conector, e ainda não tem um campo para um cabeçalho com chave de API. Um servidor que também roda localmente costuma receber a chave como variável de ambiente, que você pode definir em Ambiente.

Um servidor MCP roda com as minhas permissões?

Roda. Um servidor local é um programa no seu computador e pode fazer tudo o que a sua conta do Windows pode, então adicione só servidores em que você confia, de fontes que você conhece. O Conduit pergunta antes de executar qualquer ferramenta que altere algo, mas é o próprio servidor que decide o que cada ferramenta faz.

Isso funciona no macOS e no Linux?

Funciona. A página Conectores é a mesma em todas as plataformas. Instale o Node.js e o uv com o seu gerenciador de pacotes no lugar do winget e use caminhos como /Users/you/Documents; o resto do tutorial vale como está.

Conclusão

Neste tutorial, você instalou o Node.js e o uv, adicionou um servidor MCP local com o npx e outro com o uvx, adicionou um servidor remoto por URL e pelo registro, usou todos num chat, aprovou uma ferramenta que grava um arquivo e diagnosticou um servidor que não iniciava.

Os mesmos três campos, comando, argumentos e ambiente, são tudo de que um servidor local precisa, então os servidores do registro MCP e dos READMEs de projetos podem ser configurados do mesmo jeito. Para ir além, veja estes guias:

Baixar o Conduit

Os detalhes do Conduit correspondem à versão mais recente e podem ser conferidos na documentação e no código-fonte. Encontrou um erro? Conte para a gente e nós corrigimos.

Relacionados