Tutorial de servidor MCP em 2026: instale, configure, rode

O que é o MCP, de fato

O Model Context Protocol é uma especificação publicada pela Anthropic em novembro de 2024. Ele define um jeito padrão de modelos de linguagem chamarem ferramentas externas — e de ferramentas externas se exporem aos modelos. Antes do MCP, toda integração de ferramenta com IA era custom; com ele, integrações ficam composáveis.

A arquitetura é mais simples do que o nome sugere. Um servidor MCP é um processo que roda na sua máquina (ou remotamente, no caso de servidores hospedados). Quando o Claude Code inicia, ele sobe cada servidor MCP configurado, recebe a lista de ferramentas que aquele servidor oferece e, durante a sessão, pode chamar essas ferramentas pelo nome. Toda a comunicação acontece sobre stdin/stdout usando JSON-RPC 2.0. Sem HTTP, sem portas, sem configuração de rede para servidores locais.

Um tratamento conceitual mais profundo está no primer "O que é MCP". Este post foca no setup prático.

Onde a config mora

A configuração de servidor MCP fica em um arquivo settings.json. Há dois locais:

• ~/.claude/settings.json — global; vale para toda sessão de Claude Code nesta máquina
• .claude/settings.json (no diretório do projeto) — escopo de projeto; vale só quando o Claude Code roda nesse diretório e sobrescreve a config global para as chaves nomeadas

O arquivo de projeto é o preferido para servidores específicos do projeto (um servidor de banco amarrado à connection string daquele projeto). O arquivo global serve para servidores que você quer em qualquer lugar (Fetch, GitHub).

A estrutura básica da config

A chave mcpServers no settings.json é um mapa de nome do servidor para a configuração dele. Cada configuração diz como iniciar o processo do servidor.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/caminho/para/diretorio/permitido"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_seu_fine_grained_token_aqui"
      }
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Algumas observações sobre essa estrutura:

• A flag -y no npx instala o pacote se ele ainda não estiver presente. Conveniente no setup, um pouco mais lento na primeira execução. Você pode fixar uma versão para evitar isso: @modelcontextprotocol/server-filesystem@0.6.0.
• Credenciais vão no objeto env, não em argumentos de linha de comando. Args ficam em log; variáveis de ambiente, não (por padrão).
• Os nomes dos servidores (as chaves) são arbitrários — só aparecem em mensagens de erro e nas descrições de ferramenta para o Claude.

Os cinco servidores para instalar primeiro

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_TOKEN": "github_pat_..."
    }
  }
}

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

{
  "fetch": {
    "command": "uvx",
    "args": ["mcp-server-fetch"]
  }
}

Verificando se um servidor está funcionando

Depois de editar o settings.json, abra uma nova sessão do Claude Code. No prompt, peça ao Claude que liste as ferramentas disponíveis:

Quais ferramentas MCP você tem disponíveis?

O Claude deve listar os servidores que você configurou e suas ferramentas. Se um servidor está faltando, geralmente é uma destas três coisas:

1. O pacote não está instalado. A flag -y no npx instala, mas a primeira execução pode falhar se o registry do npm está lento ou se há firewall na rede. Rode o comando npx manualmente no terminal para ver o erro.
2. O caminho está errado. O servidor Filesystem aceita um caminho absoluto. Caminho relativo ou com erro de digitação derruba o startup. O Claude Code grava erros de servidor MCP em ~/.claude/logs/ — confira lá primeiro.
3. A credencial é inválida. Se o servidor sobe mas as ferramentas devolvem erro, a causa mais comum é uma chave de API expirada ou mal configurada. Teste a credencial direto com curl ou no playground de API do provedor antes de debugar a camada MCP.

Config de projeto vs. config global

Padrão comum na Septim: a config global tem Fetch, Memory e Playwright — servidores úteis em qualquer projeto. A config de projeto tem Filesystem (com a raiz do projeto como caminho permitido), o servidor de banco do projeto e o GitHub (com escopo no repositório do projeto).

Essa estrutura te deixa entrar em qualquer diretório de projeto e o Claude Code já pega os servidores certos automaticamente, sem ficar alternando configs na mão. O arquivo de projeto sobrescreve o global para servidores de mesmo nome, então você pode ter conexões de banco diferentes por projeto sem conflito.

Servidores MCP remotos

A Anthropic adicionou suporte a servidores MCP remotos (acessados por SSE em vez de stdio) no início de 2026. A configuração usa uma chave url no lugar de command e args:

{
  "mcpServers": {
    "stripe": {
      "url": "https://mcp.stripe.com",
      "headers": {
        "Authorization": "Bearer sk_live_..."
      }
    }
  }
}

Servidores remotos são convenientes para serviços que mantêm seus próprios endpoints MCP hospedados (Stripe e vários outros já têm). O custo é o round-trip de rede a cada chamada de ferramenta e a credencial trafegando pelo fio — só use endpoints remotos sobre HTTPS e trate o Authorization com o mesmo cuidado que uma chave de API em variável de ambiente.

Considerações de segurança antes de adicionar mais servidores

Cada servidor que você adiciona aumenta a superfície de ataque da sua sessão de Claude Code. O checklist de vulnerabilidades de servidor MCP traz o framework de avaliação em 24 pontos. A versão curta para tutoriais:

• Instale apenas servidores com mantenedor organizacional ativo ou com uma empresa por trás
• Leia as descrições de ferramenta no código-fonte antes de instalar — instruções maliciosas embutidas em metadados de ferramenta são vetor de ataque documentado (arXiv 2603.22489)
• Use o menor escopo possível de credencial — um token do GitHub para ler um único repo não deve ter escrita em todos os repos
• Mantenha o .claude/settings.json fora do git se ele contiver credenciais

A lista curada completa de servidores que valem rodar — cada um com sua ressalva de segurança — está no post melhores servidores MCP em 2026.