MCP Server

O DataSpoc Lens inclui um servidor MCP (Model Context Protocol) que permite que agentes de IA interajam com seu data lake programaticamente. Os agentes podem descobrir tabelas, executar queries, fazer perguntas em linguagem natural e gerenciar cache.

Instalar

pip install dataspoc-lens[mcp]

Iniciar o servidor

dataspoc-lens mcp

O servidor roda via transporte stdio, projetado para ser iniciado por um cliente MCP (como o Claude Desktop).

Configuração no Claude Desktop

Adicione o Lens ao arquivo de configuração MCP do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "dataspoc-lens": {
      "command": "dataspoc-lens",
      "args": ["mcp"]
    }
  }
}

Reinicie o Claude Desktop após salvar. As tabelas do Lens ficarão disponíveis para o Claude como tools MCP.

Tools disponíveis

Tool	Descrição
list_tables	Lista todas as tabelas disponíveis no data lake
describe_table	Mostra o schema (colunas e tipos) de uma tabela
query	Executa uma query SQL somente leitura (operações de escrita são rejeitadas)
ask	Traduz uma pergunta em linguagem natural para SQL e executa
cache_status	Mostra o status de todas as tabelas cacheadas localmente
cache_refresh	Força o refresh do cache local de uma tabela específica
cache_refresh_stale	Atualiza todas as tabelas cacheadas que estão stale

Detalhes das tools

list_tables Retorna um nome de tabela por linha. Sem parâmetros.

describe_table Parâmetros: table (string) — nome da tabela. Retorna array JSON de objetos {"column_name": ..., "data_type": ...}.

query Parâmetros: sql (string) — query SQL a executar. Deve ser somente leitura (SELECT, SHOW, etc.). Retorna JSON com columns, rows, row_count e duration. Operações de escrita (DROP, DELETE, INSERT, UPDATE, ALTER, TRUNCATE, CREATE, REPLACE) são rejeitadas.

ask Parâmetros: question (string) — pergunta em linguagem natural sobre os dados. Retorna JSON com sql, columns, rows, duration e error.

cache_status Retorna array JSON de objetos {"table", "status", "cached_at", "size_bytes"}.

cache_refresh Parâmetros: table (string) — nome da tabela a atualizar. Retorna JSON com cached_at, size_bytes e file_count.

cache_refresh_stale Atualiza todas as tabelas cujo status é stale. Retorna array JSON das tabelas atualizadas.

Resource

URI	Descrição
lens://tables	Catálogo completo de todas as tabelas com seus schemas de colunas

O resource lens://tables retorna um array JSON onde cada elemento contém o nome da table e suas columns (array de {column_name, data_type}).

Exemplo de conversa com agente

Depois de configurado no Claude Desktop, você pode interagir com seu data lake naturalmente:

Você: Quais tabelas eu tenho no meu data lake?

Claude (chama list_tables): Você tem 3 tabelas: customers, orders e products.

Você: Quantos pedidos foram feitos no mês passado?

Claude (chama query com SQL): Foram 4.230 pedidos no mês passado, com uma receita total de R$ 362.400.

Você: Quais clientes têm o maior ticket médio mas não compraram nos últimos 90 dias?

Claude (chama ask): Aqui estão os principais clientes inativos de alto valor:

name	avg_order_value	last_order	days_inactive
Alice Smith	$245.00	2026-01-10	95
Bob Johnson	$198.50	2025-12-28	108

Você: Cacheia a tabela orders para trabalho offline.

Claude (chama cache_refresh): Pronto. Cacheado orders: 4 arquivos, 12.3 MB. O cache agora está atualizado.

Segurança

• O servidor MCP roda com as mesmas permissões do usuário que o iniciou
• Todo controle de acesso é feito pelo IAM da nuvem — o servidor só pode acessar buckets que o usuário tem permissão de leitura
• Operações de escrita são explicitamente bloqueadas no nível da query
• Nenhuma autenticação é implementada no servidor em si