🚀 Your First MCPs

It all starts in the file ~/.claude/settings.json (global configuration) or .claude/settings.json (per project). That's where you declare each MCP server that Claude Code should start. The structure is simple: inside the key mcpServers, each entry has a name, the command to start the server, and optional settings such as arguments and environment variables.

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

The MCP Filesystem is the "hello world" of MCP servers. It exposes file operations as tools: read_file, write_file, list_directory, search_files, and more. The command’s final argument is the allowed root directory: the server only accesses files inside it (basic sandboxing).

In practice, Claude Code already has built-in access to files. MCP Filesystem is useful when you want to grant access to a directory outside from the project, or when you’re using another MCP client that doesn’t have native file access.

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

The MCP Git exposes version control operations as tools: git_status, git_diff, git_commit, git_log, git_branch. The agent can version code, create branches, and make commits without you manually typing any git commands.

The configuration is identical to the others: a block in the mcpServers. No special arguments are needed; the server detects the repository from the working directory.

The MCP SQLite gives the agent access to SQLite databases via SQL. The tools include read_query (SELECT), write_query (INSERT/UPDATE/DELETE), list_tables, e describe_table. You point it to the .db file, and the agent does the rest.

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

After configuring, you need to verify. In Claude Code, type /mcp to see the connected servers and their tools. If a server appears with "connected" status and lists its tools, it's working. If it doesn't appear, something went wrong with the config.

Test it with a simple request: “list the files in my project” (uses Filesystem), “what’s the git status?” (uses Git), “how many tables are in the database?” (uses SQLite). If the agent uses the tool and returns a result, it’s ready.

# 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% of MCP problems fall into one of these categories: (1) the command isn't in the PATH, (2) the JSON in settings.json is malformed, (3) an environment variable is missing, (4) the server crashes on startup (missing dependency). The debugging process is always the same: check the server's stderr.

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