MCP Servers: Guia Completo de Configuracao

Como MCP funciona por baixo dos panos

Galera, MCP e tipo um USB pra agentes de IA. Assim como USB padronizou a conexao entre computador e perifericos, MCP padroniza a conexao entre um modelo de linguagem e ferramentas externas. Antes do MCP, cada integracao era customizada — agora existe um protocolo unico.

A arquitetura e cliente-servidor. O cliente e a ferramenta de IA (Claude, Cursor, Codex) e o servidor e um processo que expoe 'tools' via JSON-RPC sobre stdio ou HTTP. Quando voce pede pro Claude 'consultar o banco de dados', ele chama a tool do MCP Server de PostgreSQL, que executa a query e devolve o resultado.

Cada MCP Server expoe tres tipos de recursos: tools (funcoes que o agente pode chamar), resources (dados que o agente pode ler) e prompts (templates pre-definidos). Na pratica, tools sao o que voce mais usa — tipo 'executar SQL', 'criar issue no GitHub', 'ler arquivo'.

O mais legal e que o servidor roda local na sua maquina. Seus dados nao passam por nenhuma API externa — o agente se comunica direto com o processo local. Isso resolve a preocupacao de seguranca que muita gente tem com IA acessando dados sensiveis.

Configuracao no Claude Desktop e Claude Code

No Claude Desktop, a config fica no arquivo de configuracao do app. No Claude Code (CLI), fica no .mcp.json na raiz do projeto ou no ~/.claude/settings.json pra config global. Vou mostrar os dois.

Claude Desktop

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/seu-user/projetos"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_seu_token_aqui"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost:5432/mydb"]
    }
  }
}

Esse JSON vai no arquivo claude_desktop_config.json. No Mac fica em ~/Library/Application Support/Claude/. No Windows em %APPDATA%/Claude/. Salva, reinicia o Claude Desktop e pronto — os servers aparecem automaticamente.

Claude Code (CLI)

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost:5432/mydb"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

No Claude Code, crie um arquivo .mcp.json na raiz do projeto. Ele e carregado automaticamente quando voce inicia o claude na pasta. Pra config global (todos os projetos), coloca no ~/.claude/settings.json dentro da chave mcpServers.

Dica importante: nao coloque tokens e senhas direto no JSON commitado. Use variaveis de ambiente ou um .mcp.json no .gitignore. Seguranca primeiro, galera.

20 MCP Servers uteis pra ter no seu setup

Existem dezenas de MCP Servers open source prontos pra usar. Aqui vai a lista dos que realmente fazem diferenca no dia a dia de um dev.

Essa e a lista curada. Existem mais de 100 servers no ecossistema MCP, mas esses 10 cobrem uns 90% do que um dev precisa no dia a dia. Pra ver a lista completa, confira o repositorio oficial em github.com/modelcontextprotocol/servers.

Nao instale tudo de uma vez. Comeca com filesystem e GitHub, que sao os mais uteis. Depois vai adicionando conforme a necessidade. Cada server adicional consome memoria e startup time do agente.

Criando seu proprio MCP Server em TypeScript

Quando nenhum server pronto resolve seu problema, da pra criar o seu em menos de 50 linhas de TypeScript. O SDK oficial facilita muito.

Aqui vai um exemplo minimo de MCP Server que consulta o preco do dolar:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new McpServer({
  name: 'cotacao-server',
  version: '1.0.0',
});

server.tool(
  'get_cotacao',
  'Retorna a cotacao atual do dolar em reais',
  { moeda: z.string().default('USD-BRL') },
  async ({ moeda }) => {
    const res = await fetch(`https://economia.awesomeapi.com.br/json/last/${moeda}`);
    const data = await res.json();
    const key = moeda.replace('-', '');
    return {
      content: [{ type: 'text', text: `1 USD = R$ ${data[key].bid}` }],
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Sao 25 linhas. O server expoe uma tool chamada get_cotacao que o agente pode chamar a qualquer momento. Pra configurar, adiciona no JSON do Claude apontando pra npx tsx index.ts. Simples assim.

A beleza do MCP e que qualquer API que voce ja usa no seu projeto pode virar um MCP Server. API interna da empresa? MCP Server. Webhook do Stripe? MCP Server. Servico de email? MCP Server. O agente ganha superpoderes quando tem acesso direto a essas ferramentas.

Troubleshooting: 10 erros mais comuns

MCP e relativamente novo, entao erros de config sao frequentes. Aqui vai a lista dos 10 que eu mais vejo e como resolver cada um.

A regra de ouro do troubleshooting MCP: sempre rode o comando do server manualmente no terminal primeiro. Se nao funciona no terminal, nao vai funcionar no Claude. Resolva o erro do terminal, depois volte pra config do JSON.