MCP: Como Claude Interage Inteligentemente com Seus Arquivos Locais.

O Model Context Protocol (MCP) oferece uma estrutura segura para que aplicações interajam com sistemas de arquivos por meio de operações em sandbox. Este guia explica como o MCP funciona, seus principais recursos e apresenta um exemplo prático utilizando o MCP Filesystem Server.

O que é o Model Context Protocol (MCP)?

O Model Context Protocol (MCP) é uma poderosa estrutura de segurança projetada para possibilitar interações controladas entre aplicações (como assistentes de IA) e sistemas externos, especialmente sistemas de arquivos. Atuando como uma ponte segura, o MCP permite que ferramentas realizem operações como leitura, escrita ou busca de arquivos em um ambiente controlado por permissões.

O protocolo é especialmente valioso para desenvolvedores que desejam integrar operações em sistemas de arquivos em aplicações como VS Code, Claude Desktop ou outros ambientes de desenvolvimento, mantendo limites de segurança robustos.

Principais Recursos do MCP

• Operações em Sandbox: Todas as atividades ocorrem em diretórios pré-definidos, protegendo áreas sensíveis do seu sistema de arquivos.
• API Padronizada: Um conjunto consistente de ferramentas (read_file, write_file, etc.) acessível por uma interface unificada.
• Design com Foco em Segurança: Operações restritas a diretórios permitidos, com recursos como montagens somente leitura.
• Integração Flexível: Compatível com vários ambientes incluindo Docker, NPX, VS Code e Claude Desktop.

Explicando o MCP Filesystem Server

O MCP Filesystem Server é uma implementação em Node.js criada especificamente para operações em sistemas de arquivos dentro do framework do Model Context Protocol. Ele oferece um conjunto abrangente de ferramentas para interagir com arquivos e diretórios de forma controlada.

Ferramentas Disponíveis no MCP Filesystem Server

Veja abaixo as principais funcionalidades:

• read_file: Lê o conteúdo de arquivos usando codificação UTF-8
• read_multiple_files: Processa múltiplos arquivos simultaneamente, continuando mesmo com falhas individuais
• write_file: Cria novos arquivos ou sobrescreve existentes
• edit_file: Permite edições seletivas com correspondência de padrões, incluindo dry runs e saída de diff estilo Git
• create_directory: Cria diretórios com opção de criação de diretórios pai
• list_directory: Mostra o conteúdo de diretórios com prefixos claros [FILE] ou [DIR]
• move_file: Move ou renomeia arquivos e diretórios
• search_files: Busca recursivamente por correspondências com suporte a padrões de exclusão
• get_file_info: Recupera metadados incluindo tamanho, data de criação e permissões
• list_allowed_directories: Exibe todos os diretórios acessíveis para transparência

Todas essas ferramentas são acessíveis via o recurso file://system, que serve como interface para operações de sistema de arquivos do MCP.

Usando o MCP com o Claude

Para ilustrar como o MCP funciona na prática, vamos passar por um exemplo real usando o MCP Filesystem Server com o Claude, um assistente de IA, para executar operações comuns no sistema de arquivos.

Passo 1: Listando Diretórios Permitidos

O primeiro passo foi determinar quais diretórios Claude poderia acessar. Usamos a ferramenta list_allowed_directories, que revelou dois locais permitidos:

• /Users/arshia/Desktop
• /Users/arshia/Downloads

Isso confirmou que as operações do Claude estavam restritas apenas a esses diretórios, mantendo o restante do sistema de arquivos seguro.

Passo 2: Explorando o Conteúdo dos Diretórios

Em seguida, utilizamos a ferramenta list_directory para ver quais arquivos estavam disponíveis. Os resultados mostraram:

Para /Users/arshia/Desktop:

• [FILE] DS_Store
• [FILE] localized

Para /Users/arshia/Downloads:

• [FILE] DS_Store
• [FILE] localized
• [DIR] Visual Studio Code.app
• [FILE] shrek.txt
• [FILE] claudes diary.pages
• [FILE] diary.pdf

Isso revelou um arquivo chamado shrek.txt no diretório Downloads, junto com outros arquivos e um diretório do Visual Studio Code.

Captura de tela mostrando as requisições e respostas do list_directory para os diretórios Desktop e Downloads

Passo 3: Tentando Ler um Arquivo

Com o shrek.txt identificado, tentamos ler seu conteúdo usando a ferramenta read_file. Inicialmente, fornecemos apenas o nome do arquivo shrek.txt, assumindo que a ferramenta buscaria nos diretórios permitidos.

Isso resultou em um erro:
“Acesso negado – caminho fora dos diretórios permitidos: /shrek.txt não está em /Users/arshia/Desktop, /Users/arshia/Downloads.”
O erro ocorreu porque o MCP exige caminhos completos de arquivos por questões de segurança.

Imagem 2: Captura de tela mostrando a tentativa frustrada de read_file com a mensagem de erro

Passo 4: Lendo o Arquivo com Sucesso

Após corrigirmos a abordagem, fornecemos o caminho completo /Users/arshia/Downloads/shrek.txt para a ferramenta read_file. Desta vez, a operação foi bem-sucedida, retornando o conteúdo do arquivo:

Request
{
  `path`: `/Users/arshia/Downloads/shrek.txt`
}
Response

Can you see what im writing here? If you do check this out: 

⢀⡴⠑⡄⠀⠀⠀⠀⠀⠀⠀⣀⣀⣤⣤⣤⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ 
⠸⡇⠀⠿⡀⠀⠀⠀⣀⡴⢿⣿⣿⣿⣿⣿⣿⣿⣷⣦⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠑⢄⣠⠾⠁⣀⣄⡈⠙⣿⣿⣿⣿⣿⣿⣿⣿⣆⠀⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⢀⡀⠁⠀⠀⠈⠙⠛⠂⠈⣿⣿⣿⣿⣿⠿⡿⢿⣆⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⢀⡾⣁⣀⠀⠴⠂⠙⣗⡀⠀⢻⣿⣿⠭⢤⣴⣦⣤⣹⠀⠀⠀⢀⢴⣶⣆ 
⠀⠀⢀⣾⣿⣿⣿⣷⣮⣽⣾⣿⣥⣴⣿⣿⡿⢂⠔⢚⡿⢿⣿⣦⣴⣾⠁⠸⣼⡿ 
⠀⢀⡞⠁⠙⠻⠿⠟⠉⠀⠛⢹⣿⣿⣿⣿⣿⣌⢤⣼⣿⣾⣿⡟⠉⠀⠀⠀⠀⠀ 
⠀⣾⣷⣶⠇⠀⠀⣤⣄⣀⡀⠈⠻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀ 
⠀⠉⠈⠉⠀⠀⢦⡈⢻⣿⣿⣿⣶⣶⣶⣶⣤⣽⡹⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⠀⠀⠉⠲⣽⡻⢿⣿⣿⣿⣿⣿⣿⣷⣜⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⣷⣶⣮⣭⣽⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⣀⣀⣈⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠇⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠃⠀⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⠀⠹⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠟⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⠻⠿⠿⠿⠿⠛⠉

Shrek

• Uma pergunta perguntando se o leitor consegue ver o que está sendo escrito
• Arte ASCII representando o rosto do Shrek
• O texto “Shrek” ao final

A operação bem-sucedida confirmou que o MCP pode ler arquivos quando fornecido o caminho correto dentro dos diretórios permitidos.

Lições-Chave do Nosso Exemplo

Este passo a passo prático destaca diversos aspectos importantes ao usar o MCP:

1. Caminhos Completos São Necessários: Ferramentas como read_file exigem caminhos completos, não apenas nomes de arquivos.
2. Sandbox Funciona de Forma Eficaz: A falha inicial demonstrou o modelo de segurança do MCP funcionando como projetado.
3. Exploração Iterativa é Mais Eficiente: Utilizar ferramentas de listagem de diretórios ajuda a navegar corretamente pelo sistema de arquivos.

Melhores Práticas para Implementação do MCP

Com base em nossa experiência e nos recursos do MCP Filesystem Server, recomendamos as seguintes práticas:

• Sempre Verifique as Permissões Primeiro: Use list_allowed_directories antes de tentar qualquer operação.
• Use Caminhos Completos de Arquivos: Forneça caminhos completos para evitar erros e ambiguidades.
• Teste Edições com Dry Runs: Ao usar edit_file, antecipe as mudanças com dryRun: true antes de aplicar.
• Planeje para Sucessos Parciais: Ferramentas como read_multiple_files continuam mesmo diante de falhas individuais.
• Aplique o Princípio do Menor Privilégio: Ao configurar o servidor, utilize montagens somente leitura para diretórios que não devem ser modificados.

Conclusão

O Model Context Protocol (MCP) e seu Filesystem Server oferecem uma abordagem robusta e segura para operações em sistemas de arquivos em ambientes controlados. Nosso exemplo com o Claude demonstra o uso prático de ferramentas como list_directory e read_file, ao mesmo tempo em que destaca princípios importantes como o uso de caminhos completos e a compreensão de limites de permissões.

Seguindo as melhores práticas apresentadas aqui, você pode aproveitar o MCP para integrar operações em sistemas de arquivos de forma segura em suas aplicações ou fluxos de desenvolvimento.

Para desenvolvedores que desejam implementar o MCP em seus projetos, a documentação oficial no GitHub fornece detalhes abrangentes e guias de implementação.