🚀 Seus Primeiros MCPs

Tudo comeca no arquivo ~/.claude/settings.json (configuracao global) ou .claude/settings.json (por projeto). E ali que voce declara cada MCP server que o Claude Code deve iniciar. A estrutura e simples: dentro da chave mcpServers, cada entrada tem um nome, o comando para iniciar o server, e opcionais como argumentos e variaveis de ambiente.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projetos"]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git"]
    },
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db", "/tmp/test.db"]
    }
  }
}

O MCP Filesystem e o "hello world" dos MCP servers. Ele expoe operacoes de arquivo como tools: read_file, write_file, list_directory, search_files, e mais. O argumento final do comando e o diretorio raiz permitido: o server so acessa arquivos dentro dele (sandboxing basico).

Na pratica, o Claude Code ja tem acesso a arquivos built-in. O MCP Filesystem e util quando voce quer dar acesso a um diretorio fora do projeto, ou quando esta usando outro client MCP que nao tem file access nativo.

# Testar standalone (fora do Claude Code)
npx -y @modelcontextprotocol/server-filesystem /home/user/projetos

O MCP Git expoe operacoes de versionamento como tools: git_status, git_diff, git_commit, git_log, git_branch. O agente pode versionar codigo, criar branches, e fazer commits sem voce digitar nenhum comando git manualmente.

A configuracao e identica aos outros: um bloco no mcpServers. Nao precisa de argumentos especiais; o server detecta o repositorio pelo diretorio de trabalho.

O MCP SQLite da ao agente acesso a bancos SQLite via SQL. As tools incluem read_query (SELECT), write_query (INSERT/UPDATE/DELETE), list_tables, e describe_table. Voce aponta para o arquivo .db e o agente faz o resto.

"sqlite": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db", "/path/to/database.db"]
}

Depois de configurar, voce precisa verificar. No Claude Code, digite /mcp para ver os servers conectados e suas tools. Se um server aparece com status "connected" e lista as tools, esta funcionando. Se nao aparece, algo deu errado na config.

Teste pedindo algo simples: "liste os arquivos do meu projeto" (usa Filesystem), "qual o status do git?" (usa Git), "quantas tabelas tem no banco?" (usa SQLite). Se o agente usa a tool e retorna resultado, esta pronto.

# Ver servers conectados e tools disponiveis
/mcp

# Testar pedindo ao agente:
"Liste os arquivos em /home/user/projetos"
"Qual o git status deste repositorio?"
"Quantas tabelas existem no banco /tmp/test.db?"

90% dos problemas com MCP caem em uma destas categorias: (1) o comando nao existe no PATH, (2) o JSON do settings.json esta malformado, (3) falta uma variavel de ambiente, (4) o server crasha no startup (dependencia faltando). O caminho para debugar e sempre o mesmo: checar stderr do server.

MCP nao conecta? Cheque nesta ordem:
[ ] JSON valido? (virgula sobrando, aspas faltando)
[ ] Comando existe? (which npx, which node)
[ ] Pacote instalado? (npx -y baixa, mas pode falhar offline)
[ ] Variaveis de ambiente? (env no settings ou no shell)
[ ] Testar standalone: rode o comando no terminal
[ ] Logs: Claude Code mostra stderr do server nos logs