🚀 Tus primeros MCPs

Todo comienza en el archivo ~/.claude/settings.json (configuración global) o .claude/settings.json (por proyecto). Allí declaras cada servidor MCP que Claude Code debe iniciar. La estructura es simple: dentro de la clave mcpServers, cada entrada tiene un nombre, el comando para iniciar el server y opciones como argumentos y variables de entorno.

{
  "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"]
    }
  }
}

El MCP Filesystem es el «hello world» de los servidores MCP. Expone operaciones de archivos como tools: read_file, write_file, list_directory, search_files, y más. El argumento final del comando es el directorio raíz permitido: el server solo accede a archivos dentro de él (sandboxing básico).

En la práctica, Claude Code ya tiene acceso integrado a los archivos. MCP Filesystem es útil cuando quieres dar acceso a un directorio afuera del proyecto, o cuando usas otro cliente MCP que no tiene acceso nativo a archivos.

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

El MCP Git expone operaciones de control de versiones como tools: git_status, git_diff, git_commit, git_log, git_branch. El agente puede versionar código, crear ramas y hacer commits sin que escribas ningún comando git manualmente.

La configuración es idéntica a las demás: un bloque en el mcpServers. No necesita argumentos especiales; el servidor detecta el repositorio a partir del directorio de trabajo.

El MCP SQLite da al agente acceso a bases de datos SQLite mediante SQL. Las tools incluyen read_query (SELECT), write_query (INSERT/UPDATE/DELETE), list_tables, e describe_table. Tú indicas el archivo .db y el agente hace el resto.

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

Después de configurar, tienes que verificar. En Claude Code, escribe /mcp para ver los servidores conectados y sus herramientas. Si un servidor aparece con el estado "connected" y muestra las herramientas, está funcionando. Si no aparece, algo salió mal en la configuración.

Prueba con una solicitud sencilla: «lista los archivos de mi proyecto» (usa Filesystem), «¿cuál es el estado de git?» (usa Git), «¿cuántas tablas hay en la base de datos?» (usa SQLite). Si el agente usa la herramienta y devuelve un resultado, está listo.

# 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?"

El 90% de los problemas con MCP entra en una de estas categorías: (1) el comando no existe en el PATH, (2) el JSON de settings.json está malformado, (3) falta una variable de entorno, (4) el servidor falla al iniciar (falta una dependencia). El camino para depurar es siempre el mismo: revisar el stderr del servidor.

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