MCP Server

DataSpoc Lens includes an MCP (Model Context Protocol) server that lets AI agents interact with your data lake programmatically. Agents can discover tables, run queries, ask natural language questions, and manage cache.

Install

pip install dataspoc-lens[mcp]

Start the server

dataspoc-lens mcp

The server runs on stdio transport, designed to be launched by an MCP client (such as Claude Desktop).

Claude Desktop configuration

Add Lens to your Claude Desktop MCP configuration file:

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

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

Restart Claude Desktop after saving. Lens tables will be available to Claude as MCP tools.

Available tools

Tool	Description
list_tables	List all available tables in the data lake
describe_table	Show the schema (columns and types) of a table
query	Execute a read-only SQL query (write operations are rejected)
ask	Translate a natural language question to SQL and execute it
cache_status	Show the status of all locally cached tables
cache_refresh	Force-refresh the local cache for a specific table
cache_refresh_stale	Refresh all stale cached tables

Tool details

list_tables Returns one table name per line. No parameters.

describe_table Parameters: table (string) — name of the table. Returns JSON array of {"column_name": ..., "data_type": ...} objects.

query Parameters: sql (string) — SQL query to execute. Must be read-only (SELECT, SHOW, etc.). Returns JSON with columns, rows, row_count, and duration. Write operations (DROP, DELETE, INSERT, UPDATE, ALTER, TRUNCATE, CREATE, REPLACE) are rejected.

ask Parameters: question (string) — natural language question about the data. Returns JSON with sql, columns, rows, duration, and error.

cache_status Returns JSON array of {"table", "status", "cached_at", "size_bytes"} objects.

cache_refresh Parameters: table (string) — name of the table to refresh. Returns JSON with cached_at, size_bytes, and file_count.

cache_refresh_stale Refreshes all tables where status is stale. Returns JSON array of refreshed tables.

Resource

URI	Description
lens://tables	Full catalog of all tables with their column schemas

The lens://tables resource returns a JSON array where each element contains a table name and its columns (array of {column_name, data_type}).

Example agent conversation

Once configured in Claude Desktop, you can interact with your data lake naturally:

You: What tables do I have in my data lake?

Claude (calls list_tables): You have 3 tables: customers, orders, and products.

You: How many orders were placed last month?

Claude (calls query with SQL): There were 4,230 orders placed last month, with a total revenue of $362,400.

You: Which customers have the highest average order value but haven’t ordered in 90 days?

Claude (calls ask): Here are the top dormant high-value customers:

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

You: Cache the orders table for offline work.

Claude (calls cache_refresh): Done. Cached orders: 4 files, 12.3 MB. The cache is now fresh.

Security

• The MCP server runs with the same permissions as the user who started it
• All access control is handled by cloud IAM — the server can only access buckets the user has permission to read
• Write operations are explicitly blocked at the query level
• No authentication is implemented in the server itself